steve
7e49b62e0e
Three rules to date: * After every make build, restage the agent binary + install assets into /tmp/rm-smoke/data/ and replace the running agent on this dev box. Plain `make build` doesn't reach either, and forgetting has bitten the smoke env twice today (stale agent without mergeRestCreds; stale unit without User=root). * Migrations: prefer ALTER TABLE DROP/RENAME COLUMN (SQLite 3.35+) over the rebuild dance. With foreign_keys=ON in the DSN, DROP TABLE on a parent with ON DELETE CASCADE children wipes every dependent table — and PRAGMA foreign_keys=OFF inside a migration is a no-op (PRAGMA can only change outside a tx). * Don't slog restic's merged URL. The user:pass@-embedded form exists only inside envSlice() at exec time; if any URL needs to be operator-visible, route it through restic.RedactURL. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
Project-specific rules for Claude when working in this repo.
|
|
|
|
## After building a new binary, also stage it for the smoke env
|
|
|
|
The smoke / dev environment runs the server out of `bin/` directly,
|
|
but the **agent** is fetched by the install script from the server's
|
|
`<DataDir>/agent-binaries/` directory, and the **systemd unit** + the
|
|
**install script** are fetched from `<DataDir>/install/`. Plain
|
|
`make build` doesn't touch any of those — the source-of-truth files
|
|
in the working tree (`deploy/install/*`, `bin/restic-manager-agent`)
|
|
must be copied into `/tmp/rm-smoke/data/...` *and* the running agent
|
|
on this dev host needs replacing if the change touches agent code or
|
|
the unit file.
|
|
|
|
This has bitten the smoke env twice (stale agent without
|
|
`mergeRestCreds`; stale unit without `User=root` + capabilities).
|
|
Both produced confusing test failures that looked like bugs in the
|
|
new code but were actually "old binary still running."
|
|
|
|
**Rule: after every `make build`, run the full restage block before
|
|
asking the operator to test.**
|
|
|
|
```sh
|
|
# 1. Restage what the install script serves (binary + unit + script).
|
|
cp bin/restic-manager-agent \
|
|
/tmp/rm-smoke/data/agent-binaries/restic-manager-agent-linux-amd64
|
|
cp deploy/install/install.sh \
|
|
/tmp/rm-smoke/data/install/install.sh
|
|
cp deploy/install/restic-manager-agent.service \
|
|
/tmp/rm-smoke/data/install/restic-manager-agent.service
|
|
|
|
# 2. Replace the running agent on this dev box and restart the
|
|
# service. Skip only when the change is server-side only AND
|
|
# doesn't include a unit-file edit.
|
|
sudo -n install -m 0755 bin/restic-manager-agent \
|
|
/usr/local/bin/restic-manager-agent
|
|
sudo -n install -m 0644 deploy/install/restic-manager-agent.service \
|
|
/etc/systemd/system/restic-manager-agent.service
|
|
sudo -n systemctl daemon-reload
|
|
sudo -n systemctl restart restic-manager-agent
|
|
|
|
# 3. The server runs from the working tree; restart it manually
|
|
# after a build that touches server code:
|
|
pkill -f restic-manager-server
|
|
RM_LISTEN=:8080 RM_DATA_DIR=/tmp/rm-smoke/data \
|
|
RM_BASE_URL=http://127.0.0.1:8080 \
|
|
RM_SECRET_KEY_FILE=/tmp/rm-smoke/data/secret.key \
|
|
RM_COOKIE_SECURE=false \
|
|
./bin/restic-manager-server >> /tmp/rm-smoke/server.log 2>&1 &
|
|
```
|
|
|
|
A `make smoke-deploy` target that bundles all of this would be a
|
|
good follow-up.
|
|
|
|
## Migrations: prefer column-level ALTERs over table rebuilds
|
|
|
|
SQLite ≥ 3.35 supports `ALTER TABLE ... DROP COLUMN` and
|
|
`ALTER TABLE ... RENAME COLUMN`. Use them. The
|
|
"rename-old + create-new + copy + drop-old" pattern is unsafe in
|
|
this codebase because the connection DSN sets
|
|
`PRAGMA foreign_keys=ON`, and `DROP TABLE` on a parent with
|
|
`ON DELETE CASCADE` children **wipes every dependent table**. We
|
|
hit this in migration 0007 (first draft) and lost the entire
|
|
smoke env's schedules / jobs / snapshots / host_credentials.
|
|
|
|
`PRAGMA foreign_keys = OFF` inside a migration is a no-op — that
|
|
PRAGMA can only change outside a transaction, and migrations run
|
|
in one. So the cascade-trap can't be defused that way; just avoid
|
|
the rebuild pattern when there are inbound FKs.
|
|
|
|
If a column-level ALTER won't do what you need (e.g. tightening a
|
|
CHECK), use the safe rebuild order: **create new with a temp name
|
|
→ copy → DROP old → ALTER new RENAME TO old**. Never rename the
|
|
original first; that propagates the rename into dependent FKs and
|
|
leaves them dangling after the eventual drop.
|
|
|
|
## Don't slog the merged rest-server URL
|
|
|
|
`restic.Env.RepoURL` is bare (no creds). The `user:pass@`-embedded
|
|
form is built only inside `envSlice()` at the moment of
|
|
`exec.Command` and is fed straight to the subprocess. Never store
|
|
it on a struct field. Never pass it to `slog`. If a URL needs to
|
|
appear in any operator-readable surface, run it through
|
|
`restic.RedactURL()` first — that mirrors restic's own `***`
|
|
substitution.
|