mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-20 19:16:08 +00:00
docs(db): rotating the encryption key on Postgres
This commit is contained in:
@@ -196,7 +196,7 @@ A plugin with the `db:own` permission keeps its own database. On SQLite that is
|
||||
## Maintenance tools
|
||||
|
||||
- **Resetting the admin account** works as on SQLite: `docker exec -it -u node trek node server/reset-admin.js` resets or creates the account in the Postgres database, with the server's connection settings and its write lock. It never opens or creates a `travel.db`, and it refuses to run when `TREK_DB_FILE` is set beside `TREK_DB_URL`. See [Troubleshooting](Troubleshooting).
|
||||
- **Rotating the encryption key** is not available on Postgres yet. `server/scripts/migrate-encryption.ts` stops before it changes anything when `TREK_DB_URL` is set. Keep the current `ENCRYPTION_KEY`. See [Encryption Key Rotation](Encryption-Key-Rotation).
|
||||
- **Rotating the encryption key** works as on SQLite: `docker exec -it -u node -w /app/server trek node --import tsx scripts/migrate-encryption.ts` re-encrypts the secrets in the Postgres database, through the server's connection settings and in one transaction that holds its write lock. It first writes a `pg_dump` copy to `data/pre-key-rotation-<time>.pgdump`, and it refuses to run when `DB_PATH` or `TREK_DB_FILE` is set beside `TREK_DB_URL`. See [Encryption Key Rotation](Encryption-Key-Rotation).
|
||||
|
||||
## Limitations
|
||||
|
||||
|
||||
@@ -56,9 +56,9 @@ To find your current key: check the `ENCRYPTION_KEY` environment variable or rea
|
||||
|
||||
## Rotating the key
|
||||
|
||||
Use `scripts/migrate-encryption.ts` to re-encrypt the stored secrets listed below without downtime or manual re-entry.
|
||||
Use `scripts/migrate-encryption.ts` to re-encrypt the stored secrets listed below without downtime or manual re-entry, on SQLite and on Postgres alike.
|
||||
|
||||
The script works on the SQLite database only. On a [Postgres](Database-Postgres) install (`TREK_DB_URL` set) it stops before it changes anything, because it cannot re-encrypt the secrets held in Postgres yet. Keep the current key there; rotating a `travel.db` left over from before the move would rewrite the key file while the secrets in Postgres stay under the old key.
|
||||
The script works on the database TREK runs on. Without `TREK_DB_URL` that is the SQLite file (`DB_PATH`, default `data/travel.db`). On a [Postgres](Database-Postgres) install (`TREK_DB_URL` set) it is the Postgres database, reached with the server's own connection settings (SSL included); no `travel.db` is opened, created or backed up then, and the script refuses to run when `DB_PATH` or `TREK_DB_FILE` is set beside the URL, since it would not be clear which database is meant.
|
||||
|
||||
**Docker:**
|
||||
|
||||
@@ -78,8 +78,9 @@ The script:
|
||||
|
||||
1. Prompts for the old and new encryption keys interactively (keys are never echoed to the terminal or written to shell history).
|
||||
2. Asks for confirmation before making any changes.
|
||||
3. Creates a timestamped backup of the database (e.g. `travel.db.backup-1713484800000`) before modifying anything.
|
||||
4. Re-encrypts all stored secrets across all tables:
|
||||
3. Creates a timestamped backup of the database before modifying anything: on SQLite a copy next to the file (e.g. `travel.db.backup-1713484800000`), on Postgres a `pg_dump` custom-format copy in the data directory (e.g. `data/pre-key-rotation-1713484800000.pgdump`). On Postgres it checks first that it reaches the database and that the database holds TREK's tables, and it changes nothing when the copy cannot be written (for example without the PostgreSQL client tools; the TREK image ships them). The copy loads back as described in [Rolling back a Postgres update](Updating#rolling-back-a-postgres-update).
|
||||
4. Runs the rotation as one transaction. On Postgres that transaction first takes the same write lock as every write of a running TREK, so the server's writes wait until the rotation has finished.
|
||||
5. Re-encrypts all stored secrets across all tables:
|
||||
- `app_settings`: `oidc_client_secret`, `smtp_pass`, `admin_webhook_url`, `admin_ntfy_token`, `maps_api_key`, `unsplash_api_key`, `amap_api_key`, `web_push_vapid_private_key`
|
||||
- `app_settings['storage.backends']`: the `secretAccessKey` of every S3 storage backend
|
||||
- `users` (per user): `maps_api_key`, `unsplash_api_key`, `amap_api_key`, `openweather_api_key`, `immich_api_key`, `synology_password`, `synology_sid`, `synology_did`, `airtrail_api_key`, `mfa_secret`
|
||||
@@ -93,8 +94,8 @@ The script:
|
||||
- `trip_document_links`: `webhook_secret`
|
||||
- `addons.config`: the instance-wide API key of the AI Parsing addon
|
||||
- `ai_connections`: `secrets` (the AI Assistant's API key or ChatGPT sign-in tokens; left out, the admin would have to enter the key again and every ChatGPT user would have to sign in anew)
|
||||
5. Reports counts of migrated, already-migrated, skipped (empty), and errored values.
|
||||
6. Writes the new key to `.encryption_key` next to the database, when that file exists, so the file and the secrets agree again.
|
||||
6. Reports counts of migrated, already-migrated, skipped (empty), and errored values.
|
||||
7. Writes the new key to `.encryption_key` (next to the SQLite file, or in the data directory on Postgres), when that file exists, so the file and the secrets agree again.
|
||||
|
||||
After a successful migration:
|
||||
|
||||
|
||||
@@ -537,7 +537,7 @@ from the next boot onward. The startup log prints what is actually in effect:
|
||||
[DB] journal_mode=DELETE, synchronous=FULL
|
||||
```
|
||||
|
||||
The maintenance tools that open the same file (on SQLite; with `TREK_DB_URL` they never open it) — `reset-admin.js` and `scripts/migrate-encryption.ts` — read the same two
|
||||
The maintenance tools that open the same file (on SQLite; with `TREK_DB_URL` they work on the Postgres database and never open a file) — `reset-admin.js` and `scripts/migrate-encryption.ts` — read the same two
|
||||
variables, so run them with the same environment (`docker exec` into the container does this for you). Otherwise the
|
||||
next key rotation or admin reset would quietly switch the file back to WAL.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user