From ea8f07e2bd99eddfa674024c8079bd336c1bfd38 Mon Sep 17 00:00:00 2001 From: Thomas Camlong Date: Tue, 16 Jun 2026 14:20:57 +0200 Subject: [PATCH] docs(management): move SQLite Backup & Restore out of Tools category --- .../docs/management/tools/_category_.json | 5 -- .../docs/management/tools/backup/index.mdx | 66 ------------------- 2 files changed, 71 deletions(-) delete mode 100644 apps/docs/docs/management/tools/_category_.json delete mode 100644 apps/docs/docs/management/tools/backup/index.mdx diff --git a/apps/docs/docs/management/tools/_category_.json b/apps/docs/docs/management/tools/_category_.json deleted file mode 100644 index 04139d7f9..000000000 --- a/apps/docs/docs/management/tools/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Tools", - "collapsed": true, - "position": 10 -} diff --git a/apps/docs/docs/management/tools/backup/index.mdx b/apps/docs/docs/management/tools/backup/index.mdx deleted file mode 100644 index b4f05cf28..000000000 --- a/apps/docs/docs/management/tools/backup/index.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: SQLite Backup & Restore -tags: - - Management - - Backup - - Restore - - SQLite ---- - -The SQLite Backup & Restore feature allows you to export and import your entire Homarr database as a portable ZIP file. This is useful for creating backups, migrating between instances, or recovering from failures. - -:::info SQLite only -This feature is only available when using the SQLite database driver (`DB_DRIVER=better-sqlite3`). MySQL and PostgreSQL users should use their respective database backup tools. -::: - -## Accessing Backup & Restore - -Navigate to **Management → Tools → Backup** from the sidebar. This page is only visible when running with SQLite. - -## Exporting a Backup - -Click the **Export** button to download a ZIP archive containing: - -- **`db.sqlite`** — A consistent snapshot of your database (created via `VACUUM INTO`) -- **`metadata.json`** — Contains: - - `homarrVersion` — The version of Homarr that created the backup - - `exportedAt` — Timestamp of the export - - `dbDialect` — The database dialect (`sqlite`) - - `encryptionKey` — Your `SECRET_ENCRYPTION_KEY` (needed to decrypt integration secrets) - -:::caution -The exported ZIP contains your encryption key and database. Store it securely and do not share it publicly. -::: - -A confirmation dialog will ask you to type **"I understand"** before the export proceeds. - -## Importing a Backup - -1. Click the **Import** button and upload a previously exported ZIP file -2. Homarr analyzes the backup **entirely in your browser** using WebAssembly (sql.js) — no data is sent to the server during preview -3. The preview shows: - - **Entity counts** — How many boards, apps, users, integrations, etc. are in the backup - - **Board names** — A list of all boards contained in the backup - - **Migration status** — If the backup is from an older version, Homarr shows each pending database migration as animated timeline steps -4. Review the preview and type **"I understand"** to confirm -5. Homarr applies any pending migrations, re-encrypts integration secrets if the `SECRET_ENCRYPTION_KEY` differs between instances, and replaces the live database -6. The server automatically restarts to pick up the new database - -:::tip -The import process is **backward-compatible** with older backups that used a separate `encryption-key.txt` file instead of embedding the key in `metadata.json`. -::: - -## Onboarding Integration - -When setting up a fresh Homarr instance with SQLite, the onboarding wizard includes a **"Restore from SQLite backup"** option. This lets you upload a backup ZIP to bootstrap your new instance with data from a previous installation. - -## Docker Restart Behavior - -After a successful import, only the Next.js process restarts — nginx and Redis remain running. The `run.sh` script automatically restarts Next.js in a loop, so the application comes back online within seconds. Running `docker stop` still works gracefully. - -## Best Practices - -- **Back up regularly** — Create exports before major updates or configuration changes -- **Test restores** — Periodically verify your backups by importing them on a test instance -- **Secure storage** — Keep backups in an encrypted or access-controlled location since they contain your encryption key -- **Check versions** — Backups from newer versions cannot be imported into older Homarr instances; always import into the same or newer version