Backup and Restore

What Must Be Backed Up

The RDS insightly database contains all Hivel data. This is the only component requiring backup in this AWS/RDS deployment (no separate object store).

Backup Strategy

Use RDS's native backup mechanisms:

• Automated backups: RDS takes backups on a schedule you configure, supporting point-in-time restore within the retention window

• Manual snapshots: Create one on demand before risky changes (e.g., upgrades)

aws rds create-db-snapshot \
  --db-instance-identifier <your-rds-instance-id> \
  --db-snapshot-identifier insightly-manual-$(date +%Y-%m-%d)

Backups run against the live, running deployment without pausing services or integration polling—RDS captures a consistent point-in-time image without blocking writes.

Recommended Configuration

Set up automated backups with:

• Frequency: Daily

• Retention window: 7 days

Adjust this cadence to your organization's requirements; 7 days is a starting recommendation.

Setting Up Automated Backups

In AWS Console:

1. Navigate to RDS > Databases

2. Select your insightly instance

3. Go to Maintenance & Backups

4. Set Automated Backups to enabled

5. Configure retention period (e.g., 7 days)

6. Save changes

---

Creating Manual Snapshots

Run this command on the VM before upgrades or other risky changes:

aws rds create-db-snapshot \
--db-instance-identifier <your-rds-instance-id> \
--db-snapshot-identifier insightly-manual-$(date +%Y-%m-%d)

Restore Decision: Choose Your Approach

Option A: Restore to a New RDS Instance

• Creates a new RDS instance from a snapshot

• Requires updating DB_HOST in .env to point to the new instance

• Use when you want to keep the original instance intact

Option B: In-Place Point-In-Time Restore (PITR)

• Restores the original RDS instance to a previous state

• Does not change the instance endpoint

• Use when you want to restore directly into the same instance

Both approaches are valid. Choose one before proceeding.

Restore Execution

Step 1: Stop Services

On the VM:

./deploy.sh --stop

Step 2: Restore from Snapshot

If using Option A (new instance):

aws rds restore-db-instance-from-db-snapshot \
  --db-instance-identifier insightly-restored \
  --db-snapshot-identifier <snapshot-id>

If using Option B (in-place PITR): Use AWS Console or AWS CLI following AWS's standard PITR documentation.

Step 3: Update Database Connection (Option A only)

Edit config/.env on the VM:

DB_HOST=<new-instance-endpoint>

Use Phase 2 (application-user) credentials from Environment Configuration.

Skip this step if using Option B (in-place PITR) — the endpoint does not change.

Step 4: Restart Services

On the VM:

./deploy.sh --start

Step 5: Validate Deployment

Use the validation checklist in Verification and Access to confirm services, endpoints, and database connectivity.

Step 6: Re-evaluate Permissions

Run this command to re-evaluate permissions after restore:

curl --location --request DELETE '<base-url>/hivelapi/v1/permissions/reevaluate?orgId=1'

Substitute <base-url> with your deployment's actual API base URL (e.g., http://localhost or your custom domain).This call re-evaluates permissions after a restore. This step is required as part of all restore sequences, not only when permissions appear incorrect.

Next step: Upgrade and Rollback.

Back to Troubleshooting

Upgrade and Rollback