Skip to content

Source: docs/adr/0008-release-layout-on-the-box.md. Edit it there; this page is generated at build time.

Releases live in Deployer's own layout under /var/www/blog-filament, owned by the deploy user and never writable by PHP ​

Every piece of the pipeline still to be written — deploy.php, the vhost, the systemd units, the rollback script — codes against where a release sits on disk and who may write to it. This records that contract once, so that each of them can be written from it rather than implying its own version.

/var/www/blog-filament/                deploy:deploy 0755
├── .dep/                              Deployer's state: releases_log, latest_release, deploy.lock
├── releases/
│   ├── 11/                            one per deploy; code 0644/0755, owned by deploy
│   └── 12/
│       ├── .env -> ../../shared/.env
│       ├── storage -> ../../shared/storage
│       ├── bootstrap/cache/           per release; ACL-writable by www-data
│       └── public/storage -> …/storage/app/public   (artisan storage:link)
├── shared/
│   ├── .env                           deploy 0600, rewritten by every deploy (ADR 0007)
│   └── storage/                       uploads, logs, framework cache; ACL-writable by www-data
└── current -> releases/12             what nginx serves, via $realpath_root

/var/backups/blog-filament/            deploy:deploy 0700
└── pre-deploy-<tag>-<utc>.sql.gz      0600, newest 10 kept

/etc/blog-filament/env-key             root:deploy 0640 (ADR 0007)

The root is /var/www/blog-filament. Not a home directory: the app today runs from /home/ghalib/projects, so any account that can read that home can read the application, and the tree's lifetime is tied to a person's account. /var/www is where nginx on Debian already looks and where the next person to SSH in will look first. /srv would do as well; it lost only because nothing on this box uses it and /var/www already exists. The name matches /etc/blog-filament/ from ADR 0007 and the pool and vhost in deploy/, so one word finds every piece of this app on the box.

Releases are named by Deployer's counter — releases/12 — not by the tag. The ticket asked for the name a human reads when they SSH in, and the tag is the obvious answer; Deployer's source rules it out. deploy:release refuses any release name that already exists, and it advances .dep/latest_release only when the name is numeric. So a deploy of v1.3.0 that fails halfway leaves releases/v1.3.0 behind, and retrying the same tag — the first thing anyone does — aborts with Release name "v1.3.0" already exists. A compound name such as 12-v1.3.0 looks like it has both properties, but it isn't numeric, so the counter never moves and every name after it has to be managed by us. The tag is not lost: every release's target is written to .dep/releases_log, and dep releases prints it next to the release number, date and commit. Reading one file to find out what is live is an acceptable price for a retry that just works.

shared/ holds exactly .env and storage/, Deployer's Laravel defaults. storage/ goes over whole rather than only storage/app/public: it holds uploaded media (medialibrary writes to the public disk), logs a person will want across releases, and the framework's cache — and splitting it only moves the question of what else under it matters. Production runs MySQL, so there is no SQLite file to share. public/storage is recreated in each release by artisan storage:link rather than shared, because it is a pointer into storage/, not data.

Five releases are kept, pruned by Deployer's own deploy:cleanup. A release is roughly 250 MB with vendor/ and node_modules/ (144 MB and 102 MB, measured on a development tree), so five is roughly 1.25 GB of a disk with 36 GB free. Five is not for disk; it is for rollback. Rolling back past the release before last means running code against a schema several releases newer than it was written for — safe only if every migration in between kept to the additive rule in CLAUDE.md — and nobody will pick the fifth-newest release in a hurry. Holding more buys nothing but a longer list to choose the wrong one from.

deploy owns the whole tree and PHP-FPM, running as www-data, cannot write to any of it except storage/ and bootstrap/cache/. This is the property the layout exists to guarantee. Code is 0644/0755: www-data reads it and cannot change it, so a file-write bug or a compromised plugin cannot rewrite the application. The two writable paths get POSIX ACLs rather than group ownership, using Deployer's default writable_mode => 'acl' with http_user => 'www-data' and no sudo: deploy grants u:www-data:rwX and u:deploy:rwX on directories it owns, plus the same as default ACLs so every file created later inherits both. The alternatives fail on this box specifically. Group ownership (chgrp/sticky) breaks the first time www-data writes a log file under umask 022 and deploy can no longer rotate it. chown to www-data needs root on every deploy, which the tooling research (issue #18) and ADR 0007 already refused to grant. The ACL path needs neither — Deployer skips a directory whose ACL is already set, which is precisely the case of a shared storage/ full of files www-data created. Verified on the box on 2026-09-19 before recording this: with ACLs set by deploy without sudo, www-data wrote a file, deploy then appended to that www-data-owned file, www-data could not create a file in the release root, and www-data could not list the dumps directory. acl was not installed and now is.

.env stays 0600 and owned by deploy, outside the ACL grant, so the running application cannot read its own credentials file. That holds only while config is cached and nothing outside config/ calls env() — the reason ADR 0007 gives, restated here because this layout is what enforces it.

Pre-migration dumps go to /var/backups/blog-filament/, owned by deploy, 0700, newest ten kept. Outside the release tree because the migrations research (issue #17) found that a dump kept inside releases/ is deleted by the same prune that deletes the release it was meant to outlive. The research wrote this path as /var/backups/reviewly/; it is renamed to match every other path here. Ten rather than five because dumps are taken only when a migration is pending, so they cover more history than the same number of releases, and the database is small enough today that ten compressed dumps cost little. Revisit the count if du -sh on that directory ever says otherwise. The directory is 0700 because a dump holds every row, including the admin users' password hashes; www-data has no business reading it and the check above confirms it cannot. Pruning belongs to the dump task in deploy.php (issue #22), run after a successful dump, never before one.

What this gives up: a person reading ls releases/ sees numbers, not versions, and has to run dep releases or read .dep/releases_log to translate them. And ACLs are invisible to ls -l — a + after the mode is the only sign — so someone debugging a permission error with ls alone will be misled. getfacl storage is the command that tells the truth.