@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.
- package/CHANGELOG.md +30 -0
- package/LICENSE +21 -0
- package/README.md +243 -2
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.d.ts.map +1 -0
- package/dist/cli/main.js +16 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/cli/run.d.ts +15 -0
- package/dist/cli/run.d.ts.map +1 -0
- package/dist/cli/run.js +442 -0
- package/dist/cli/run.js.map +1 -0
- package/dist/contract.d.ts +41 -0
- package/dist/contract.d.ts.map +1 -0
- package/dist/contract.js +15 -0
- package/dist/contract.js.map +1 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +30 -0
- package/dist/index.js.map +1 -0
- package/dist/messages/en.d.ts +17 -0
- package/dist/messages/en.d.ts.map +1 -0
- package/dist/messages/en.js +17 -0
- package/dist/messages/en.js.map +1 -0
- package/dist/messages/index.d.ts +22 -0
- package/dist/messages/index.d.ts.map +1 -0
- package/dist/messages/index.js +4 -0
- package/dist/messages/index.js.map +1 -0
- package/dist/offsite/config.d.ts +45 -0
- package/dist/offsite/config.d.ts.map +1 -0
- package/dist/offsite/config.js +147 -0
- package/dist/offsite/config.js.map +1 -0
- package/dist/offsite/crypto.d.ts +22 -0
- package/dist/offsite/crypto.d.ts.map +1 -0
- package/dist/offsite/crypto.js +48 -0
- package/dist/offsite/crypto.js.map +1 -0
- package/dist/offsite/dump.d.ts +23 -0
- package/dist/offsite/dump.d.ts.map +1 -0
- package/dist/offsite/dump.js +85 -0
- package/dist/offsite/dump.js.map +1 -0
- package/dist/offsite/index.d.ts +13 -0
- package/dist/offsite/index.d.ts.map +1 -0
- package/dist/offsite/index.js +15 -0
- package/dist/offsite/index.js.map +1 -0
- package/dist/offsite/lifecycle.d.ts +17 -0
- package/dist/offsite/lifecycle.d.ts.map +1 -0
- package/dist/offsite/lifecycle.js +45 -0
- package/dist/offsite/lifecycle.js.map +1 -0
- package/dist/offsite/objects.d.ts +19 -0
- package/dist/offsite/objects.d.ts.map +1 -0
- package/dist/offsite/objects.js +44 -0
- package/dist/offsite/objects.js.map +1 -0
- package/dist/offsite/postgres.d.ts +32 -0
- package/dist/offsite/postgres.d.ts.map +1 -0
- package/dist/offsite/postgres.js +97 -0
- package/dist/offsite/postgres.js.map +1 -0
- package/dist/offsite/record.d.ts +3 -0
- package/dist/offsite/record.d.ts.map +1 -0
- package/dist/offsite/record.js +10 -0
- package/dist/offsite/record.js.map +1 -0
- package/dist/offsite/restore.d.ts +54 -0
- package/dist/offsite/restore.d.ts.map +1 -0
- package/dist/offsite/restore.js +67 -0
- package/dist/offsite/restore.js.map +1 -0
- package/dist/offsite/s3.d.ts +34 -0
- package/dist/offsite/s3.d.ts.map +1 -0
- package/dist/offsite/s3.js +119 -0
- package/dist/offsite/s3.js.map +1 -0
- package/dist/offsite/sigv4.d.ts +19 -0
- package/dist/offsite/sigv4.d.ts.map +1 -0
- package/dist/offsite/sigv4.js +69 -0
- package/dist/offsite/sigv4.js.map +1 -0
- package/dist/offsite/status-sql.d.ts +10 -0
- package/dist/offsite/status-sql.d.ts.map +1 -0
- package/dist/offsite/status-sql.js +37 -0
- package/dist/offsite/status-sql.js.map +1 -0
- package/dist/offsite/upload.d.ts +33 -0
- package/dist/offsite/upload.d.ts.map +1 -0
- package/dist/offsite/upload.js +98 -0
- package/dist/offsite/upload.js.map +1 -0
- package/dist/offsite/verify.d.ts +32 -0
- package/dist/offsite/verify.d.ts.map +1 -0
- package/dist/offsite/verify.js +75 -0
- package/dist/offsite/verify.js.map +1 -0
- package/dist/schema.d.ts +150 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +15 -0
- package/dist/schema.js.map +1 -0
- package/dist/server/index.d.ts +28 -0
- package/dist/server/index.d.ts.map +1 -0
- package/dist/server/index.js +98 -0
- package/dist/server/index.js.map +1 -0
- package/examples/backup-verify.yml +84 -0
- package/migrations/0001_create_runs.sql +21 -0
- package/module.json +12 -0
- package/package.json +73 -4
- package/src/cli/main.ts +16 -0
- package/src/cli/run.ts +441 -0
- package/src/contract.ts +47 -0
- package/src/index.ts +41 -0
- package/src/messages/en.ts +16 -0
- package/src/messages/index.ts +6 -0
- package/src/offsite/config.ts +173 -0
- package/src/offsite/crypto.ts +53 -0
- package/src/offsite/dump.ts +97 -0
- package/src/offsite/index.ts +33 -0
- package/src/offsite/lifecycle.ts +47 -0
- package/src/offsite/objects.ts +54 -0
- package/src/offsite/postgres.ts +115 -0
- package/src/offsite/record.ts +11 -0
- package/src/offsite/restore.ts +108 -0
- package/src/offsite/s3.ts +144 -0
- package/src/offsite/sigv4.ts +84 -0
- package/src/offsite/status-sql.ts +45 -0
- package/src/offsite/upload.ts +116 -0
- package/src/offsite/verify.ts +97 -0
- package/src/schema.ts +17 -0
- 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
|
-
#
|
|
1
|
+
# @softure-ai/backup
|
|
2
2
|
|
|
3
|
-
|
|
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 @@
|
|
|
1
|
+
{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":""}
|
package/dist/cli/main.js
ADDED
|
@@ -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"}
|