dcaed9934e
IMPLEMENTATION.md hadn't been updated after the second implementation pass — the data model SQL was missing prev_ciphertext/prev_nonce, can_write, and the entire vault_grants_previous table; the Rotation section described the old "overwritten, not versioned" behavior (the opposite of what got built); the crypto scheme section still said "read implies write" while the Resolved design decisions section below it said the opposite; the CLI surface listing was missing --purge/--previous/--read-only; and "What was verified" only covered the first verification pass, not the read-only/rollback/purge one. README's Core model was missing any mention of the retention/purge behavior or read/write grant scoping. INTEGRATION.md now recommends --read-only for deploy identities specifically, now that the capability exists. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
3.7 KiB
Incorporating keep into an existing deploy setup
Concrete, by deploy pattern rather than by naming specific projects — the shape of the fit depends on how a project currently gets its config onto a target machine, not on what the project is.
The general shape
Wherever a deploy script or a manually-maintained .env exists today, the
change is the same: replace "assume .env is already sitting there,
hand-copied at some point" with a keep pull at the top of the script.
# before — a deploy script assumes .env already exists on this machine
set -euo pipefail
source .env # or docker-compose reads it directly
# after
set -euo pipefail
keep pull <project>/<env> --out .env
The one-time setup cost per machine: keep identity init once, send the
printed public key to whoever runs keep recipient add, then
keep identity set-id <id> with what comes back. After that, every future
deploy from that machine just works — no more "wait, what's the DB
password again" when setting up a new box.
A deploy identity should almost always be granted read-only access
(keep grant <vault> <deploy-recipient-id> --read-only) — it only ever
needs to pull, and a read-only grant means a compromised deploy box
can't also rotate the vault or add itself more recipients.
Pattern: docker-compose reading a local .env
A common shape — docker compose up -d reads environment: values from
a .env file sitting next to docker-compose.yml on the deploy machine,
hand-maintained and containing real secrets.
keep pull myapp/production --out .env
docker compose up -d
No code changes needed in the target project — keep only changes how
the .env file gets there, not what reads it. This is the easiest
category to retrofit.
Pattern: cross-compile + scp + SSH-restart deploy scripts
A shape where a deploy script builds a binary locally, ships it to a VPS,
and restarts a service over SSH — reading a local .env next to the
script for things like shared secrets that shouldn't be hardcoded or
re-typed on every invocation.
keep pull myapp/production --out .env
set -a && source .env && set +a
# ...rest of the deploy script unchanged
Same retrofit as the docker-compose case, just applied before whatever build/ship step already exists.
Pattern: a plaintext config file served to a browser
Not every config.js/similar file that looks like environment config
actually holds secrets — some of it is public-by-design (an API base URL,
a feature flag) that's explicitly meant to be visible to anyone loading
the page. keep solves a confidentiality problem; a file with nothing
confidential in it doesn't have one. Worth checking this distinction
before wiring keep into anything — retrofitting a non-secret config
file would be solving a problem that file doesn't have.
A vault server's own configuration
Whatever runs keep itself needs its own ADMIN_PASSWORD to be a real,
manually-set secret on its own host — it can't bootstrap its own trust
root by pulling itself from itself. This is the same "root of trust
starts somewhere unmanaged" fact every secrets system has (Vault's own
unseal keys aren't stored in Vault either). Not a gap, just worth being
explicit about: keep's own deploy stays on a plain .env/
docker-compose.yml environment variables.
New projects going forward
The actual best use case isn't retrofitting existing deploys — it's never
having the "hand-reconstruct a .env from memory" moment for a new
deploy target in the first place. For whatever gets built next: register
its production host as a keep recipient as part of first setup, write
the deploy script to keep pull from day one, and the annoyance this was
built to fix never has a chance to happen.