Backup & Restore
Relevant source files
The following files were used as context for generating this wiki page:
Hearth provides a robust backup system to protect household data. The system creates encrypted snapshots of the SQLite database and uploads them to configured destinations. Backups are never written unencrypted to offsite storage, requiring a configured ENCRYPTION_KEY to function.
The project supports two distinct backup operating modes:
- Server Backups: Automated or manual backups of the self-hosted server's SQLite database to S3, SFTP, or local storage.
- Standalone Backups: Manual JSON-based exports and imports for the mobile shell's local encrypted SQLite database.
Sources: src/app/(app)/settings/backups/page.tsx:75-77, ios-shell/www/app.js:1062-1065
Server Backup Architecture
The server backup process involves creating a temporary SQLite snapshot, encrypting it using AES-256-GCM, and transferring it to a single active destination.
Backup Process Flow
The diagram shows the sequential steps taken by the backup scheduler to secure and store data.
Sources: src/lib/backup/scheduler.ts:31-72
Components and Functions
| Component | Responsibility | Key Functions |
|---|---|---|
| Scheduler | Orchestrates the backup lifecycle and logging. | runBackup() |
| Snapshot | Creates a live VACUUM INTO copy of the SQLite DB. | createSnapshot() |
| Encryption | Secures the buffer using the system encryption key. | encryptBuffer() |
| Destinations | Handles protocol-specific uploads (S3, SFTP, Local). | uploadToS3(), uploadToSftp(), uploadToLocal() |
| Retention | Removes old backups exceeding the retentionCount. | pruneS3(), pruneSftp(), pruneLocal() |
Sources: src/lib/backup/scheduler.ts:16-25, src/lib/backup/snapshot.ts:5, tests/unit/backup-local.test.ts:24-34
Backup Destinations
Hearth supports three primary offsite destinations. Only one destination is active at any given time, as selected in the Administrative settings.
S3-Compatible Storage
The system connects to AWS S3, Backblaze B2, Cloudflare R2, or MinIO. It supports custom endpoints, region selection, and path-style URLs.
Sources: src/lib/backup/s3.ts, src/components/AppSettingsForms.tsx:300-320
SFTP (Secure File Transfer Protocol)
Backups are transferred via SFTP using either password authentication or PEM-formatted private keys.
Sources: src/lib/backup/sftp.ts, src/components/AppSettingsForms.tsx:325-342
Local Storage
Encrypted backups are written to a specific directory on the host server. This is typically used to place backups within a volume already covered by host-level backup processes.
Sources: src/lib/backup/local.ts, src/components/AppSettingsForms.tsx:290-297
Data Security and Encryption
All server backups are encrypted before leaving the server. The encryption uses AES-256-GCM.
This diagram illustrates the transformation of data from a live database to an encrypted file on a remote server.
Sources: src/lib/backup/scheduler.ts:42-45, e2e/specs/16-backup-restore.spec.ts:39-42
Standalone Mobile Backups
In standalone mode, the Hearth mobile shell manages its own backups independently of the server infrastructure. These are manual exports that bundle both record metadata and actual document file contents into a single JSON snapshot.
Standalone Backup Structure
- Format: Custom JSON format (
hearth-standalone-backup). - Contents: Encrypted SQLite table rows and Base64-encoded document files.
- Import Logic: Merges by record ID; existing records are updated while new records are inserted.
Sources: ios-shell/www/app.js:1062-1080, ios-shell/www/app.js:1115-1122
Mobile Backup Tables
Standalone backups include the following core tables:
local_profile, contracts, products, vehicles, vehicle_items, properties, home_items, rental_agreements, rental_statements, inventory_items, trips, trip_segments, portfolios, holdings, trades, documents, inbox_documents, and reminder_delivery_logs.
Sources: ios-shell/www/app.js:256-274
Configuration and Retention
Backups are governed by administrative settings that define the frequency and lifespan of stored data.
| Setting | Type | Description |
|---|---|---|
backup.cron | Cron String | Determines when automatic backups run (e.g., 0 3 * * *). |
backup.retentionCount | Integer | The number of recent backups to keep per destination. |
backup.destination | Enum | The active storage provider (S3, SFTP, LOCAL, or NONE). |
Sources: src/lib/appSettings.ts, src/components/AppSettingsForms.tsx:368-372, src/lib/actions/app-settings.ts:133-145
Restore Process
Restoration involves decrypting a .db.enc file back into a valid SQLite database format.
- Locate File: Retrieve the specific encrypted file from the storage destination.
- Decrypt: Use the
ENCRYPTION_KEYthat was active when the backup was created to decrypt the buffer. - Verify: The decrypted buffer must start with the
SQLite format 3\0magic header. - Deploy: Replace the active
contracts.dbwith the decrypted file.
Sources: e2e/specs/16-backup-restore.spec.ts:42-53
Summary
Hearth's backup and restore system ensures data durability through automated, encrypted offsite storage. By requiring an encryption key and offering multiple standard storage protocols, it provides both security and flexibility for self-hosted household management. Standalone mobile users benefit from a similar, albeit manual, JSON-based backup mechanism to preserve device-local data.