7 / 8

Deploy to a VPS

Everything so far has happened on one machine. Real projects live on servers, though — and a server needs the Athanor binary, the encrypted file, and, more importantly, the key to open it.

What athanor deploy does

athanor deploy user@my-vps

Step by step:

1. obtain a linux/amd64 athanor binary
   (if the current machine is already linux/amd64 — just a copy of the
    running binary; otherwise a rebuild from source is needed, see below)
        │
        ▼
2. validate local files; prepare <remote_path>.athanor-staging
        │
        ▼
3. scp: binary, normalized athanor.yaml, secrets, identity → staging
        │
        ▼
4. chmod 700 <staging> && chmod 600 <manifest/secrets/identity>
                        && chmod 755 <binary>
        │
        ▼
5. smoke test in staging; then activate with backup and rollback
        │
        ▼
6. repeat the smoke test in <remote_path>

remote_path isn't a command-line flag — it comes from deploy.remote_path in athanor.yaml, a project setting rather than something you pass each time.

SSH and SCP run non-interactively (BatchMode=yes) with a connection timeout. The live copy is untouched until activation. If the final smoke test fails, the previous files are restored automatically. The deployed manifest uses a local ./<secrets_file name>, so an absolute or external path from the developer machine never leaks into the VPS layout.

The private key itself goes to the server — worth saying plainly

This deserves to be stated outright, not buried in the step list above: deploy copies the identity file — the actual private key that decrypts secrets.enc.yaml — to the VPS, protected only by file permissions (chmod 600), with no separate encryption on top. That's a genuinely different trust boundary than "the secrets are encrypted": once the identity is on that server, the server can decrypt everything that key protects. It's a deliberate trade-off — without the key there, athanor run simply couldn't work on that machine — but it's exactly why a VPS you trust less deserves its own key (athanor init --own-key for that one project) instead of the one shared across everything else.

Deploy doesn't manage SSH access

deploy doesn't store or ask for a password or key to log into the server — it calls the system's ssh/scp directly, against whatever host you gave it (an alias from ~/.ssh/config, or user@host), using whatever you already have set up: a key in ssh-agent, or in the config. If logging in needs a password instead of a key, the command just fails at the first ssh call rather than trying to collect that password somehow. Application secrets and access to the server itself are two separate trust boundaries, and deploy keeps them that way.

Cross-compiling, and ATHANOR_SRC_DIR

deploy runs from your project's directory — a web app, say — not from Athanor's own repository, so there's no Athanor source to build from there. Which means:

• if the machine you're deploying from is already linux/amd64 (the same Linux the VPS runs), it just copies the already-running binary — no rebuild needed;
• if the architectures differ — deploying from a Mac to a linux/amd64 VPS, say — you'll need the ATHANOR_SRC_DIR environment variable pointing at a checkout of Athanor's own source, so it can cross-compile GOOS=linux GOARCH=amd64 from there.

Several projects on one VPS

How multiple projects coexist on one server is a question for the manifest (chapter 3), not for deploy:

• separate secrets — just different remote_path values per project; deploy never crosses the streams;
• secrets shared locally — both manifests may point at one secrets_file, but each deploy copies a snapshot into its own remote_path. Separate VPS directories are not synchronized automatically.