@softure-ai/backup 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/LICENSE +21 -0
  3. package/README.md +243 -2
  4. package/dist/cli/main.d.ts +3 -0
  5. package/dist/cli/main.d.ts.map +1 -0
  6. package/dist/cli/main.js +16 -0
  7. package/dist/cli/main.js.map +1 -0
  8. package/dist/cli/run.d.ts +15 -0
  9. package/dist/cli/run.d.ts.map +1 -0
  10. package/dist/cli/run.js +442 -0
  11. package/dist/cli/run.js.map +1 -0
  12. package/dist/contract.d.ts +41 -0
  13. package/dist/contract.d.ts.map +1 -0
  14. package/dist/contract.js +15 -0
  15. package/dist/contract.js.map +1 -0
  16. package/dist/index.d.ts +22 -0
  17. package/dist/index.d.ts.map +1 -0
  18. package/dist/index.js +30 -0
  19. package/dist/index.js.map +1 -0
  20. package/dist/messages/en.d.ts +17 -0
  21. package/dist/messages/en.d.ts.map +1 -0
  22. package/dist/messages/en.js +17 -0
  23. package/dist/messages/en.js.map +1 -0
  24. package/dist/messages/index.d.ts +22 -0
  25. package/dist/messages/index.d.ts.map +1 -0
  26. package/dist/messages/index.js +4 -0
  27. package/dist/messages/index.js.map +1 -0
  28. package/dist/offsite/config.d.ts +45 -0
  29. package/dist/offsite/config.d.ts.map +1 -0
  30. package/dist/offsite/config.js +147 -0
  31. package/dist/offsite/config.js.map +1 -0
  32. package/dist/offsite/crypto.d.ts +22 -0
  33. package/dist/offsite/crypto.d.ts.map +1 -0
  34. package/dist/offsite/crypto.js +48 -0
  35. package/dist/offsite/crypto.js.map +1 -0
  36. package/dist/offsite/dump.d.ts +23 -0
  37. package/dist/offsite/dump.d.ts.map +1 -0
  38. package/dist/offsite/dump.js +85 -0
  39. package/dist/offsite/dump.js.map +1 -0
  40. package/dist/offsite/index.d.ts +13 -0
  41. package/dist/offsite/index.d.ts.map +1 -0
  42. package/dist/offsite/index.js +15 -0
  43. package/dist/offsite/index.js.map +1 -0
  44. package/dist/offsite/lifecycle.d.ts +17 -0
  45. package/dist/offsite/lifecycle.d.ts.map +1 -0
  46. package/dist/offsite/lifecycle.js +45 -0
  47. package/dist/offsite/lifecycle.js.map +1 -0
  48. package/dist/offsite/objects.d.ts +19 -0
  49. package/dist/offsite/objects.d.ts.map +1 -0
  50. package/dist/offsite/objects.js +44 -0
  51. package/dist/offsite/objects.js.map +1 -0
  52. package/dist/offsite/postgres.d.ts +32 -0
  53. package/dist/offsite/postgres.d.ts.map +1 -0
  54. package/dist/offsite/postgres.js +97 -0
  55. package/dist/offsite/postgres.js.map +1 -0
  56. package/dist/offsite/record.d.ts +3 -0
  57. package/dist/offsite/record.d.ts.map +1 -0
  58. package/dist/offsite/record.js +10 -0
  59. package/dist/offsite/record.js.map +1 -0
  60. package/dist/offsite/restore.d.ts +54 -0
  61. package/dist/offsite/restore.d.ts.map +1 -0
  62. package/dist/offsite/restore.js +67 -0
  63. package/dist/offsite/restore.js.map +1 -0
  64. package/dist/offsite/s3.d.ts +34 -0
  65. package/dist/offsite/s3.d.ts.map +1 -0
  66. package/dist/offsite/s3.js +119 -0
  67. package/dist/offsite/s3.js.map +1 -0
  68. package/dist/offsite/sigv4.d.ts +19 -0
  69. package/dist/offsite/sigv4.d.ts.map +1 -0
  70. package/dist/offsite/sigv4.js +69 -0
  71. package/dist/offsite/sigv4.js.map +1 -0
  72. package/dist/offsite/status-sql.d.ts +10 -0
  73. package/dist/offsite/status-sql.d.ts.map +1 -0
  74. package/dist/offsite/status-sql.js +37 -0
  75. package/dist/offsite/status-sql.js.map +1 -0
  76. package/dist/offsite/upload.d.ts +33 -0
  77. package/dist/offsite/upload.d.ts.map +1 -0
  78. package/dist/offsite/upload.js +98 -0
  79. package/dist/offsite/upload.js.map +1 -0
  80. package/dist/offsite/verify.d.ts +32 -0
  81. package/dist/offsite/verify.d.ts.map +1 -0
  82. package/dist/offsite/verify.js +75 -0
  83. package/dist/offsite/verify.js.map +1 -0
  84. package/dist/schema.d.ts +150 -0
  85. package/dist/schema.d.ts.map +1 -0
  86. package/dist/schema.js +15 -0
  87. package/dist/schema.js.map +1 -0
  88. package/dist/server/index.d.ts +28 -0
  89. package/dist/server/index.d.ts.map +1 -0
  90. package/dist/server/index.js +98 -0
  91. package/dist/server/index.js.map +1 -0
  92. package/examples/backup-verify.yml +84 -0
  93. package/migrations/0001_create_runs.sql +21 -0
  94. package/module.json +12 -0
  95. package/package.json +73 -4
  96. package/src/cli/main.ts +16 -0
  97. package/src/cli/run.ts +441 -0
  98. package/src/contract.ts +47 -0
  99. package/src/index.ts +41 -0
  100. package/src/messages/en.ts +16 -0
  101. package/src/messages/index.ts +6 -0
  102. package/src/offsite/config.ts +173 -0
  103. package/src/offsite/crypto.ts +53 -0
  104. package/src/offsite/dump.ts +97 -0
  105. package/src/offsite/index.ts +33 -0
  106. package/src/offsite/lifecycle.ts +47 -0
  107. package/src/offsite/objects.ts +54 -0
  108. package/src/offsite/postgres.ts +115 -0
  109. package/src/offsite/record.ts +11 -0
  110. package/src/offsite/restore.ts +108 -0
  111. package/src/offsite/s3.ts +144 -0
  112. package/src/offsite/sigv4.ts +84 -0
  113. package/src/offsite/status-sql.ts +45 -0
  114. package/src/offsite/upload.ts +116 -0
  115. package/src/offsite/verify.ts +97 -0
  116. package/src/schema.ts +17 -0
  117. package/src/server/index.ts +111 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,30 @@
1
+ # Changelog
2
+
3
+ Newest first. Each version lists what changed for an app that uses the module. When an app has run a version in
4
+ production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
5
+ "Definition of done").
6
+
7
+ ## 0.1.1
8
+
9
+ - **`softure-backup run` for a host without a server (RP-9):** the whole night's copy in one command for an app on
10
+ Cloudflare Workers, run from a scheduled workflow. It dumps the database at `BACKUP_DATABASE_URL` with
11
+ `pg_dump --format=custom` (to stdout, so `BACKUP_PG_DUMP` can be a `postgres:<major>` wrapper; `--config=deploy.json`
12
+ leaves out `database.excludeTableData`), uploads it with the same code, key names and write-only token as `upload`,
13
+ and writes the same row into `backup.runs` over the same URL. A failed dump is recorded as `dump_failed` and nothing
14
+ is uploaded; a row that cannot be written fails the run. The reader side is unchanged and now declared
15
+ Workers-safe (`.` and `./server` in `softure.workers`), so `getLastBackup()` and the gauges run on either host.
16
+ - Database URLs (`BACKUP_DATABASE_URL`, `BACKUP_RESTORE_DATABASE_URL`, `BACKUP_VERIFY_DATABASE_URL`) and their
17
+ passwords are redacted from every message, as the S3 secrets already were.
18
+
19
+ ## 0.1.0
20
+
21
+ - **First version (#1210):** encrypted off-site copies of the nightly backup of `@softure-ai/deploy`. `softure-backup
22
+ upload` encrypts the night's dump (and data archive) with `age` to `BACKUP_AGE_RECIPIENT` and PUTs it to any
23
+ S3-compatible store (R2, B2, Hetzner, MinIO, AWS) under `<prefix>/<file>.age` with a write-only token; it never
24
+ lists, reads or deletes, and the bucket's lifecycle rule (`softure-backup lifecycle`) expires old copies. Each run
25
+ is recorded in `backup.runs` (the module's migration): time, result (`ok`, `failed`, `not_configured`), objects
26
+ with size and sha256, a safe error code and message. The app reads it with `getLastBackup()` and
27
+ `listBackupRuns()` and exports `registerBackupMetrics()` gauges (`softure.backup.last_success.age` for an alert
28
+ above 26 h). `softure-backup restore` restores into a new database unless `--overwrite --into=<db>`;
29
+ `softure-backup verify` restores the newest copy into a throwaway database, runs the deploy's schema guard and row
30
+ counts and drops it; `fetch` decrypts a data archive. The private key comes from a file or stdin only.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SOFTURE
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,244 @@
1
- # Temporary Holding Version
1
+ # @softure-ai/backup
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Encrypted off-site copies of the nightly backup of [`@softure-ai/deploy`](../../tools/deploy/README.md), their status
4
+ for the app, and a restore and a weekly verify that need a private key the server never holds.
5
+
6
+ ## 1. What it provides
7
+
8
+ - **`softure-backup upload`**, run by `deploy.sh maintain` right after the night's `pg_dump` (step `offsite-backup`):
9
+ it encrypts the new dump (and the data archive, when the app has `data.backupPaths`) with
10
+ [age](https://age-encryption.org) to a **public key** and PUTs it to any S3-compatible store (AWS S3, Cloudflare R2,
11
+ Backblaze B2, Hetzner Object Storage, MinIO, SeaweedFS…) as `<prefix>/<file>.age`, with a **write-only token**. It
12
+ never lists, reads or deletes anything remote: the bucket's lifecycle rule expires old copies. No second `pg_dump`,
13
+ no extra compose service: it reuses the dump `maintain` already took.
14
+ - **A status row per run** in `backup.runs`: start and end time, result (`ok`, `failed`, `not_configured`), each
15
+ object's key, size and sha256, and on failure a safe error code and message (no secret, no URL).
16
+ - **For the app:** `getLastBackup(db)` (the newest run and the newest successful one, for a settings screen),
17
+ `listBackupRuns(db, { limit })`, `getLastSuccessAgeSeconds(status, now)`, `registerBackupMetrics({ db })`
18
+ (OpenTelemetry gauges through `@softure-ai/observability`, among them the age of the newest good copy for an alert
19
+ above 26 hours) and a health check of the table.
20
+ - **For the operator:** `softure-backup restore` (into a **new** database by default; over an existing one only with
21
+ `--into=<db> --overwrite`), `softure-backup fetch` (decrypt one object, e.g. the data archive), `softure-backup
22
+ verify` (newest copy → throwaway database → the deploy's schema guard and row counts → drop; meant to run weekly,
23
+ see [examples/backup-verify.yml](examples/backup-verify.yml)) and `softure-backup lifecycle` (the bucket rule).
24
+ - The private key is read from a file or stdin only. An argument that holds `AGE-SECRET-KEY-` is refused, so the key
25
+ never shows in `ps` or a shell history.
26
+
27
+ ## 2. Installation
28
+
29
+ ```bash
30
+ npm install @softure-ai/backup
31
+ ```
32
+
33
+ Then add the module to `softure.config.ts` (section 3) and run `softure migrate`: the table is what the nightly run
34
+ writes its status into. The server does not need the package installed: `deploy.sh` runs the CLI with `npx` (or in
35
+ its helper tools image on a host without Node), at the version the deploy release pins.
36
+
37
+ ## 3. Configuration
38
+
39
+ ```ts
40
+ // softure.config.ts
41
+ import { backup } from "@softure-ai/backup";
42
+
43
+ export default defineConfig({
44
+ modules: [/* … */, backup()],
45
+ });
46
+ ```
47
+
48
+ There are no options: everything the off-site copy needs comes from the environment (section 6), so the code is the
49
+ same with and without it. An app that never sets `BACKUP_S3_BUCKET` sees `not_configured` and nothing fails.
50
+
51
+ **The deploy side.** `softure-deploy init` (0.7.0 and later) writes into the compose file of an app with a database an
52
+ `x-offsite-backup` block of optional names, which makes `env render` put them into `.env.prod`:
53
+
54
+ ```yaml
55
+ x-offsite-backup:
56
+ BACKUP_S3_ENDPOINT: ${BACKUP_S3_ENDPOINT:-}
57
+ BACKUP_S3_REGION: ${BACKUP_S3_REGION:-}
58
+ BACKUP_S3_BUCKET: ${BACKUP_S3_BUCKET:-}
59
+ BACKUP_S3_PREFIX: ${BACKUP_S3_PREFIX:-}
60
+ BACKUP_S3_ACCESS_KEY_ID: ${BACKUP_S3_ACCESS_KEY_ID:-}
61
+ BACKUP_S3_SECRET_ACCESS_KEY: ${BACKUP_S3_SECRET_ACCESS_KEY:-}
62
+ BACKUP_AGE_RECIPIENT: ${BACKUP_AGE_RECIPIENT:-}
63
+ ```
64
+
65
+ No container gets these values: only `deploy.sh maintain` reads them on the host and hands them to the CLI's
66
+ environment. `deploy.json` needs nothing new; `database.rowCountTables` and `database.excludeTableData` are what
67
+ `verify --config=deploy.json` counts.
68
+
69
+ ## 4. Mounting
70
+
71
+ Nothing to mount: no route or page. A settings screen reads the status on the server:
72
+
73
+ ```ts
74
+ import { getLastBackup, getLastSuccessAgeSeconds } from "@softure-ai/backup/server";
75
+
76
+ const status = await getLastBackup(db); // { result, lastRun, lastSuccess }
77
+ const ageSeconds = getLastSuccessAgeSeconds(status, new Date()); // null until a run succeeded
78
+ ```
79
+
80
+ Metrics, once at start-up next to `startObservability()`: `registerBackupMetrics({ db })`. The `@softure-ai/ops`
81
+ health route picks up the module's health check (the table exists and answers).
82
+
83
+ ## 5. Migrations and tables
84
+
85
+ Schema `backup`, migration `0001_create_runs.sql`, table `backup.runs`: `id`, `started_at`, `finished_at`, `result`
86
+ (`ok`, `failed`, `not_configured`), `objects` (jsonb: kind `database` or `data`, key, bytes, sha256), `size_bytes`,
87
+ `error_code`, `error_message`. A constraint keeps an error exactly on failed runs. The host writes the rows through
88
+ `psql` as the Postgres superuser (`POSTGRES_USER`) and prunes rows older than 400 days in the same transaction; the
89
+ app only reads them.
90
+
91
+ ## 6. Environment variables
92
+
93
+ On the server (`.env.prod`, from the deploy job), all optional; `BACKUP_S3_BUCKET` switches the off-site copy on:
94
+
95
+ | Name | What it is |
96
+ | --- | --- |
97
+ | `BACKUP_S3_ENDPOINT` | The store's S3 endpoint, `https://…` (`http://` only for a local store). |
98
+ | `BACKUP_S3_REGION` | The signing region; default `auto` (R2). AWS needs the bucket's region. |
99
+ | `BACKUP_S3_BUCKET` | The bucket. |
100
+ | `BACKUP_S3_PREFIX` | The folder in the bucket; default the app's name. One prefix per app, so apps can share a bucket. |
101
+ | `BACKUP_S3_ACCESS_KEY_ID`, `BACKUP_S3_SECRET_ACCESS_KEY` | The **write-only** token (secret). |
102
+ | `BACKUP_AGE_RECIPIENT` | The age **public** key, `age1…`. Not a secret. |
103
+
104
+ On the operator's machine or the verify job, never on the server: the same endpoint, region, bucket and prefix, plus
105
+ `BACKUP_S3_READ_ACCESS_KEY_ID` and `BACKUP_S3_READ_SECRET_ACCESS_KEY` (the **read-only** token),
106
+ `BACKUP_RESTORE_DATABASE_URL` / `BACKUP_VERIFY_DATABASE_URL` (a superuser's `postgres://` URL of the Postgres to
107
+ restore into) and optionally `BACKUP_PG_RESTORE` (the `pg_restore` to run; it must be at least the server's major).
108
+ The private key is not an environment variable of the CLI: pass it with `--identity=<file>` or `--identity=-`.
109
+
110
+ Every name is validated with zod: some names set but not all, a bad endpoint, bucket, prefix or recipient is
111
+ `config_invalid`, listed by name and never by value. Secret values are redacted from every message.
112
+
113
+ ## 7. Switches
114
+
115
+ None. Whether the copy runs is the presence of `BACKUP_S3_BUCKET` on the server.
116
+
117
+ ## 8. Appearance
118
+
119
+ No components; the app renders `getLastBackup()` in its own UI.
120
+
121
+ ## 9. Copy
122
+
123
+ `src/messages/en.ts` (`backupMessages`): a label per result (`result.ok`, `result.failed`, `result.not_configured`)
124
+ and a sentence per error code (`errors.config_invalid`, `file_missing`, `encrypt_failed`, `upload_denied`,
125
+ `upload_failed`, `network_error`) for a settings screen. English only; an app overrides them through its message
126
+ layer.
127
+
128
+ ## 10. Hooks
129
+
130
+ None in the app. On the server the step is part of `maintain`; its line is `step|offsite-backup|ok|<n> object(s), <bytes>
131
+ bytes in <s> s` or `step|offsite-backup|ok|not configured`. A failed upload does not stop the steps after it (test
132
+ restore, cleanup, hooks); `maintain` then ends `result|failed|offsite-backup|<message>`, which the cron's mail or log
133
+ shows. When the app has no `backup.runs` table yet, the copy still runs and the step line ends `; status not recorded
134
+ (add @softure-ai/backup to the app and migrate)`.
135
+
136
+ ## 11. GDPR
137
+
138
+ `backup.runs` holds no personal data. The copies hold the whole database, encrypted, so a person's erased data lives on
139
+ in them until the lifecycle rule expires them: keep the rule's days (default 30) in the privacy policy's retention
140
+ section. The module exports and deletes nothing for a user.
141
+
142
+ ## 11a. On Cloudflare (a host without a server)
143
+
144
+ The package keeps one interface on every host: the same `BACKUP_*` settings, object keys, `backup.runs` row,
145
+ `getLastBackup()`, gauges, `restore`, `fetch` and `verify`. Only the producer of the nightly copy changes. On a VPS it
146
+ is `deploy.sh maintain`; on Cloudflare (`platform: { host: "cloudflare" }`) it is `softure-backup run`, called by the
147
+ [`backup-cloudflare`](../../.github/actions/backup-cloudflare/action.yml) action from the nightly `backup.yml` that
148
+ `softure-deploy init --host=cloudflare` writes:
149
+
150
+ ```bash
151
+ BACKUP_DATABASE_URL=postgres://… npx @softure-ai/backup run --app=acme-app --config=deploy.json --summary=summary.md
152
+ ```
153
+
154
+ `run` dumps the database over `BACKUP_DATABASE_URL` (`pg_dump --format=custom`, the deploy config's
155
+ `excludeTableData` honoured; `--pg-dump=<path>` names another binary, the action uses a `postgres:<major>` container),
156
+ encrypts and uploads it exactly as `upload` does, and inserts the run's row with that same connection, so the URL's
157
+ role must be able to write `backup.runs` (the migrator, `MIGRATE_DATABASE_URL`, does). Without `BACKUP_S3_*` it says
158
+ `not configured` and exits 0; a failed dump, upload or row exits 1, and a copy whose row could not be written is
159
+ reported as such. The URL and its password are redacted from every message. Move steps: docs/07-runtime-providers.md,
160
+ "Backups on Cloudflare".
161
+
162
+ ## 12. Limitations
163
+
164
+ - One PUT per file, up to 5 GiB per encrypted object (no multipart upload). A larger database needs a store-side
165
+ replication instead.
166
+ - The write-only property is the token's: the CLI never reads or deletes, but only the provider can make the token
167
+ unable to. Where a provider has no write-only key, turn on its object lock (section "Owner guide", step 2).
168
+ - `verify` needs the private key, so it cannot run in `maintain`: run it weekly from a CI job or the owner's machine.
169
+ The server's own weekly `verify-backup` step keeps checking the local dump.
170
+ - Retention is the bucket's lifecycle rule only; nothing here deletes a remote object.
171
+
172
+ ## Owner guide
173
+
174
+ What the owner does once per app (or once per bucket shared by several apps on one server, each with its own prefix).
175
+
176
+ 1. **Bucket.** Create a private bucket in a region other than the server's, e.g. `acme-backups`. No public access, no
177
+ website hosting. Note its S3 endpoint (R2: `https://<account id>.r2.cloudflarestorage.com`, region `auto`; B2:
178
+ `https://s3.<region>.backblazeb2.com`; AWS: `https://s3.<region>.amazonaws.com`; Hetzner:
179
+ `https://<location>.your-objectstorage.com`).
180
+ 2. **Write-only token** for the server, limited to that bucket:
181
+ - AWS: an IAM user with only `s3:PutObject` on `arn:aws:s3:::acme-backups/<prefix>/*`.
182
+ - Backblaze B2: an application key restricted to the bucket with the single capability `writeFiles`.
183
+ - MinIO / SeaweedFS: a user or identity with a `PutObject`-only (`Write:<bucket>`) policy.
184
+ - A provider whose keys cannot be write-only (Cloudflare R2's object tokens read and write; Hetzner's keys are
185
+ per project): scope the key to the bucket and turn on the bucket's object lock / bucket lock rule for at least
186
+ the retention days, so a stolen key can neither delete nor overwrite a copy.
187
+ 3. **Read-only token** for restore and verify, separate from the write one: AWS `s3:GetObject` on the prefix plus
188
+ `s3:ListBucket` on the bucket; B2 `readFiles` + `listFiles`; R2 "Object Read only". It never goes to the server.
189
+ 4. **Lifecycle rule** (the only remote retention): `npx @softure-ai/backup lifecycle --app=<prefix> --days=30` prints
190
+ the S3 XML (`--format=json` for `aws s3api put-bucket-lifecycle-configuration`); on R2 and B2 set the same in the
191
+ bucket's settings (expire objects with prefix `<prefix>/` after 30 days).
192
+ 5. **age key pair**, on the owner's machine: `age-keygen -o backup-key.txt`. The `# public key: age1…` line is
193
+ `BACKUP_AGE_RECIPIENT`. Keep `backup-key.txt` offline (a password manager and a printed copy), never on the server
194
+ and never in the deploy's environment. Losing it makes every copy unreadable.
195
+ 6. **Secrets in the GitHub Environment** of the deploy (e.g. `production`): secrets `BACKUP_S3_ACCESS_KEY_ID`,
196
+ `BACKUP_S3_SECRET_ACCESS_KEY`; variables `BACKUP_S3_ENDPOINT`, `BACKUP_S3_REGION`, `BACKUP_S3_BUCKET`,
197
+ `BACKUP_S3_PREFIX`, `BACKUP_AGE_RECIPIENT`. The deploy job must pass them on: name the two secrets in the deploy
198
+ action's `secret-names` (or the caller's `app-secrets`) and the variables in `app-vars`
199
+ ([deploy workflow](../../tools/deploy/README.md#deploy-workflow)). The next release writes them into `.env.prod`;
200
+ the next night's `maintain` uploads.
201
+ 7. **Weekly verify:** copy [examples/backup-verify.yml](examples/backup-verify.yml) into the app's repository with its
202
+ own GitHub Environment `backup-verify` (read token, prefix, and the private key as `BACKUP_AGE_IDENTITY` if the
203
+ owner accepts it there), or run `verify` by hand on the owner's machine each week.
204
+ 8. **Alert** on the metric: `softure_backup_last_success_age_seconds > 93600` (26 h) for 15 minutes, and on
205
+ `softure_backup_last_run_ok == 0`.
206
+
207
+ ### Restore and verify
208
+
209
+ ```bash
210
+ export BACKUP_S3_ENDPOINT=… BACKUP_S3_REGION=… BACKUP_S3_BUCKET=… BACKUP_S3_PREFIX=acme-app
211
+ export BACKUP_S3_READ_ACCESS_KEY_ID=… BACKUP_S3_READ_SECRET_ACCESS_KEY=…
212
+ export BACKUP_RESTORE_DATABASE_URL=postgres://postgres:…@127.0.0.1:5432/acme_app
213
+
214
+ # The newest copy into a new database acme_app_restore_<yyyymmddhhmmss>, named after the URL's database (nothing
215
+ # existing is touched):
216
+ npx @softure-ai/backup restore --identity=backup-key.txt
217
+ # A given copy: --key=acme-app/db-20261109T031700Z.dump.age; over an existing database: --into=acme_app --overwrite
218
+
219
+ # The weekly check: restore, schema guard, row counts, drop (BACKUP_VERIFY_DATABASE_URL instead):
220
+ npx @softure-ai/backup verify --identity=- --config=deploy.json --migrations-dir=softure-migrations < backup-key.txt
221
+ ```
222
+
223
+ ### After losing the server
224
+
225
+ 1. Provision the new server as the first time (host playbook, DNS), and run the deploy workflow for the last
226
+ release's tag. That first release starts Postgres with the app's roles (`initdb/01-roles.sql`), migrates an empty
227
+ database and starts the app.
228
+ 2. On the owner's machine, decrypt the newest copies (read token and key as above):
229
+ `npx @softure-ai/backup fetch --identity=backup-key.txt --kind=database --out=db.dump`, and with a data volume
230
+ `npx @softure-ai/backup fetch --identity=backup-key.txt --kind=data --out=data.tar.gz`.
231
+ 3. Copy them to the server (`scp db.dump data.tar.gz admin@host:/tmp/`) and, as the admin user in `/srv/<app>`:
232
+ stop the app and worker (`docker compose --env-file .env.prod stop app worker`), restore over the empty database
233
+ (`docker compose --env-file .env.prod exec -T postgres pg_restore --clean --if-exists --exit-on-error -U postgres
234
+ -d <database> < /tmp/db.dump`), and unpack the data archive into the data volume
235
+ (`docker compose --env-file .env.prod run --rm --no-deps -T -v /tmp:/in --entrypoint tar app -xzf /in/data.tar.gz
236
+ -C <data path>`).
237
+ 4. Start everything again (`docker compose --env-file .env.prod up -d`), check `GET /api/health`, then delete
238
+ `/tmp/db.dump` and `/tmp/data.tar.gz` (they are not encrypted).
239
+ 5. The next night's `maintain` uploads again under the same prefix; `getLastBackup()` shows it the morning after.
240
+
241
+ ## Build
242
+
243
+ `npm run build -w modules/backup` runs `tsc -p tsconfig.build.json`. Releasing:
244
+ [scripts/release/README.md](../../scripts/release/README.md).
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=main.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":""}
@@ -0,0 +1,16 @@
1
+ #!/usr/bin/env node
2
+ import { runCli } from "./run.js";
3
+ async function readStdin() {
4
+ const chunks = [];
5
+ for await (const chunk of process.stdin)
6
+ chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
7
+ return Buffer.concat(chunks).toString("utf8");
8
+ }
9
+ process.exitCode = await runCli(process.argv.slice(2), {
10
+ cwd: process.cwd(),
11
+ env: process.env,
12
+ stdout: (text) => process.stdout.write(text),
13
+ stderr: (text) => process.stderr.write(text),
14
+ readStdin,
15
+ });
16
+ //# sourceMappingURL=main.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,KAAK,UAAU,SAAS;IACtB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAgB,CAAC,CAAC;IACzH,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,OAAO,CAAC,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IACrD,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAClB,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAC5C,SAAS;CACV,CAAC,CAAC"}
@@ -0,0 +1,15 @@
1
+ import { type RunRecord } from "../offsite/upload.js";
2
+ export interface CliIo {
3
+ readonly cwd: string;
4
+ readonly env: Readonly<Record<string, string | undefined>>;
5
+ readonly stdout: (text: string) => void;
6
+ readonly stderr: (text: string) => void;
7
+ /** The text of stdin, read only for `--identity=-`. */
8
+ readonly readStdin: () => Promise<string>;
9
+ readonly now?: () => Date;
10
+ readonly fetch?: typeof fetch;
11
+ /** Writes a run's row in `backup.runs` (`run`); a connection to the URL by default. */
12
+ readonly recordRun?: (url: string, record: RunRecord) => Promise<void>;
13
+ }
14
+ export declare function runCli(argv: readonly string[], io: CliIo): Promise<number>;
15
+ //# sourceMappingURL=run.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAuBA,OAAO,EAA2C,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAG/F,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,uFAAuF;IACvF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAgXD,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAmChF"}