Skip to content

Source: docs/adr/0007-encrypted-production-env.md. Edit it there; this page is generated at build time.

Production config is committed encrypted and keyed from the box, so that config rolls back with the code ​

Three ways to get production config onto the server were considered. GitHub Actions secrets, written into shared/.env by the deploy workflow. Server state: a .env created by hand once, living only in shared/, which is what Forge and Envoyer do and is the simplest thing that works. And Laravel's env:encrypt/env:decrypt, committing the ciphertext and keeping the key on the box. We chose the third.

The reason is not secrecy, and the map's original phrasing — that the point of a self-hosted runner is that the key never reaches GitHub — overstates the protection. Anyone with write access to this repo can push a tagged commit whose workflow runs cat /etc/blog-filament/env-key on the box. In access-control terms the encrypted file and a GitHub secret have the same blast radius: repo write access means production credentials, either way. What differs is who else holds the plaintext (GitHub the company does, under the second option, forever and in a store we cannot audit) and, decisively, whether config is versioned with the code it configures. This pipeline is built on tags being the pointer to what is live and on rollback being a symlink flip back to the previous release. Under GitHub secrets, rolling back to v1.2.0 gets last quarter's code running against today's config, and the mismatch is invisible until something reads a key that release never knew about. Checking out a tag gets its .env.production.encrypted. Server state fails a different way: the entire production configuration becomes undocumented, unversioned, unbacked-up state on a single box, and it is gone when the box is.

GitHub secrets are not banished entirely — they hold credentials the pipeline needs, such as the Telegram webhook token, which the runner must have before the application exists and whose loss costs nothing. The line is that the app's configuration lives in the encrypted file and the pipeline's lives in GitHub, so neither store has to be consulted about the other.

The committed artifact is a whole-file blob, .env.production.encrypted, at the default AES-256-CBC. The tempting alternative is --prune's neighbour --readable, which encrypts each value separately and leaves variable names in plain text, on the theory that a reviewer could then see which setting changed. It cannot: every value is encrypted under a fresh random IV, so re-encrypting a file where one value changed rewrites every line. Encrypting the same three-line file twice, changing one value, produced three changed lines both times. What --readable does deliver is the complete list of every service this site integrates with and every class of credential it holds, published in a file that survives the repo ever being made public. That is reconnaissance in exchange for a diff signal that does not exist. The cipher is left at its default for a narrower reason: env:encrypt and env:decrypt each default to AES-256-CBC independently, so choosing aes-256-gcm would mean every future decrypt needs a matching --cipher flag, and the one that forgets it fails on the box, mid-deploy. No command in this scheme passes --cipher, so none can omit it.

The .gitignore was already correct and nobody knew it. git check-ignore -v confirms .env.production is ignored by line 5 and .env.production.encrypted is ignored by nothing, because git matches that pattern as an exact filename rather than a prefix. Correct, load-bearing, and entirely accidental: tidying the three .env lines into one .env.* — a change that looks like housekeeping — would start ignoring the ciphertext, and the next deploy would fail on a missing file. So the negation is now written explicitly, with the reason beside it, and tests/Feature/EncryptedEnvTest.php asserts both halves against git check-ignore itself rather than against a re-implementation of git's matching rules. The rule has no other enforcement, and CI is where this repo already catches things.

The key lives at /etc/blog-filament/env-key, owned root:deploy, mode 0640. The ticket floated a root-only file and a systemd EnvironmentFile, which solve different problems and neither of which reaches this one: the deploy is not a service, so no EnvironmentFile is injected into it, and a root-only file would put sudo in the deploy path — the same privilege the tooling research already refused to grant for an FPM reload, refused here for the same reason. Keeping it outside /home/deploy means a compromise of the deploy account can read the key but not rewrite it, and root stays the only account that can rotate. It is deliberately not an Environment= line in the runner's own systemd unit, which would place the key in the environment of every job that runner ever executes, including workflows nobody has written yet.

There is no chicken-and-egg, which is the ticket's main premise and it is wrong. env:decrypt was run with .env moved out of the tree entirely and APP_KEY unset in the environment; it exited 0 and wrote the correct plaintext. The command builds its own Encrypter from LARAVEL_ENV_ENCRYPTION_KEY and never resolves the application's encrypter, and Laravel boots a console command without an env file. So the bootstrap is only an ordering constraint: the key file must exist on the box before the first tag is pushed. Everything before that happens on a developer's machine — build .env.production from .env.example, env:encrypt it, record the key offline before doing anything else, commit the ciphertext — and everything after it is an ordinary deploy.

The decrypted file must be written through a temporary file, not directly into shared/. EnvironmentDecryptCommand writes with $this->files->put() and passes no mode, so under the default umask 022 the plaintext lands 0644 — world-readable, which is precisely what the ticket's cleanup requirement forbids, arriving by default. A umask 077 around the command fixes the case where the file is created and not the case where it already exists, and shared/.env will already exist from the second deploy onward, so the umask alone silently does nothing thereafter. Decrypting to {{release_path}}/.env.tmp, chmod 0600, then mv -f into shared/.env is correct in both cases and never leaves the path empty. The mode is 0600 rather than 0640 because nothing but the deploy reads it: artisan:optimize caches the configuration, and there is no env() call anywhere outside config/ in this repo, so the running application under PHP-FPM never opens .env at all. That is a property worth keeping — the day someone adds env() to a controller, this file has to become readable by www-data and the reason for the tighter mode is gone.

The deploy task is hooked after deploy:shared and before artisan:optimize, because config caching reads the env and a cache built first would hold the wrong values. Corrected by ADR 0010: the task runs after deploy:vendors, not after deploy:shared. A rehearsed deploy failed here because artisan cannot boot before vendor/ exists. It still runs before artisan:optimize, which is the ordering this paragraph is really about. It reads the key inline rather than exporting it, so it exists in exactly one process:

php
task('env:decrypt', function () {
    run('cd {{release_path}} && umask 077 && '
      . 'LARAVEL_ENV_ENCRYPTION_KEY=$(cat /etc/blog-filament/env-key) '
      . '{{bin/php}} artisan env:decrypt --env=production '
      . '--path={{release_path}} --filename=.env.tmp --force && '
      . 'chmod 0600 {{release_path}}/.env.tmp && '
      . 'mv -f {{release_path}}/.env.tmp {{deploy_path}}/shared/.env');
});

Every deploy overwrites shared/.env, which is correct — the ciphertext is the source of truth — and also means any hand-edit made to shared/.env on the box is destroyed by the next deploy without a word. That is the intended behaviour and the surprise is unavoidable, so it belongs where someone at 2am will meet it: a comment at the top of the generated file.

Changing one production value is four commands, and the last one deletes the plaintext so there is no cleanup step to forget:

sh
php artisan env:decrypt --env=production --key="$KEY" --force    # writes .env.production
$EDITOR .env.production
php artisan env:encrypt --env=production --key="$KEY" --force --prune
git commit .env.production.encrypted -m "…" && git tag vX.Y.Z && git push --tags

Rotating the key is the same loop with two keys — decrypt with the old, env:encrypt --key="$NEW" --force --prune, have root replace /etc/blog-filament/env-key, then commit and tag. Order barely matters, because deploys are triggered by hand: a tag pushed before the box's key is updated fails at the decrypt step, which is before the symlink flip, so the old release keeps serving and the cost is a failed deploy rather than a broken site.

Rotating the encryption key does not rotate APP_KEY, and APP_KEY must never rotate at all. It is generated once with key:generate --show on a developer's machine — never the development key, and never key:generate on the box, which would rewrite a file that the ciphertext no longer matches — and then it is fixed forever, because changing it invalidates every session and makes any value already encrypted at rest unreadable. This is what makes losing /etc/blog-filament/env-key worse than losing a password: reissuing every credential it held is merely laborious, but the APP_KEY inside it cannot be reissued, and data encrypted under it is gone. The key therefore lives in a password manager entry named for its path on the box, plus a second copy in a different place. One copy is not a backup, and a password manager has its own lockout modes.

The trade-off we accept is friction on exactly the operation most likely to be performed under pressure. Changing a production value means decrypt, edit, encrypt, commit, tag and deploy, where a GitHub secret would have been a web form and a re-run. We are buying, with that friction, the guarantee that any tag can be checked out and deployed as the thing it was — and paying for it a handful of times a year.