One repo for every static site you host
If you self-host for long enough you end up with a pile of small websites: a landing page, a joke site a friend asked for in 2013, a mirror of some web toy, a redirect or two. Each one was set up on a different afternoon, so each has its own folder, its own nginx config written from memory, and its own idea of what a 404 looks like. None of it is in version control.
This post describes the layout I moved mine into. It is nothing clever. The point is that the layout is small enough to remember, and that redeploying is one command.
The layout#
sites/<domain>/ the web root, deployed verbatim
sites/<domain>/.deploy-keep directories that live only on the server
nginx/snippets/common.conf shared hardening, included by every vhost
nginx/snippets/php.conf the PHP-FPM handler, for the one site that needs it
nginx/sites/<domain>.conf one vhost per domain
deploy.sh rsync + nginx -t + reload
Everything a browser fetches is under sites/. Everything nginx reads is under
nginx/[1]. A site that is only a redirect has a vhost and no folder[2].
Keep big files out of git without losing them#
Two of my sites carry media that has no business in a repository: a hundred megabytes
of audio and a mirror of a web toy with its own asset packs. They stay on the server.
The folder they live in is named in the site’s .deploy-keep file, one path per line:
media/
The deploy script turns each line into two rsync arguments[3]:
args=(-az --delete --exclude=.deploy-keep)
while IFS= read -r keep; do
[ -n "$keep" ] || continue
args+=("--exclude=$keep" "--filter=protect $keep")
done < "sites/$s/.deploy-keep"
rsync "${args[@]}" "sites/$s/" "server:/srv/www/$s/"
--exclude stops rsync from uploading the directory[4]. --filter=protect stops
--delete from removing it on the receiving side because it is missing from the
source[4]. Strictly, the exclude alone already keeps the media: rsync treats a plain
exclude as a protect too, and only --delete-excluded turns that off[5]. The explicit
protect rule still holds if someone adds that flag later. Test it on a copy before trusting
it.
One snippet for the boring parts#
Every vhost includes the same file[6]:
autoindex off;
server_tokens off;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
error_page 404 /404.html;
location = /404.html { internal; }
location ~ /\. { deny all; }
autoindex off is the one that mattered to me. One of my old vhosts had it on, so a
folder I had forgotten about was a browsable listing on the public internet[7]. If you take
one thing from this post, grep your configs for autoindex.
A vhost then becomes a few lines:
server {
listen 80;
server_name example.com;
root /srv/www/example.com;
index index.html;
include snippets/common.conf;
location / { try_files $uri $uri/ $uri.html =404; }
}
The $uri.html lets /about serve about.html, so pages do not need a folder each[8].
The deploy script#
Before anything is overwritten, the live vhost directory is copied to a timestamped
backup next to it. Then the confs are uploaded and nginx -t runs inside the
container[9]. If that fails, the script stops and nothing has been reloaded; the old
confs are still in the backup. Only after the test passes does it sync the site
folders and reload[1].
That ordering is what makes it safe to run. A typo in a vhost cannot take the sites down on deploy: nothing reloads, and nginx would keep its old configuration even if a reload were sent[1]. The broken confs do stay on disk, so copy the backup back before the container next restarts. Site content is not in that backup; a bad sync is fixed by deploying again from the repo.
What I left out#
There is no build step for the plain sites and I intend to keep it that way. The blog
you are reading is the one exception: about 150 lines of Python turn Markdown into HTML
into the same sites/ folder, and the deploy script runs it first. No framework, no
node_modules, nothing to upgrade.
Updated: 2026-10-14
Sources#
-
Beginner’s Guide, nginx documentation. How the configuration is built from directives, blocks and
serverblocks, whatnginx -s reloaddoes, and that a reload with a broken configuration leaves the old one running. ↩︎↩︎↩︎ -
Module ngx_http_rewrite_module: return, nginx documentation. It answers with a status code and a redirect URL, so a redirect needs no files on disk. ↩︎
-
rsync(1) manpage, rsync project. Reference for
-a,-z,--deleteand the other options. ↩︎ -
rsync(1) manpage: FILTER RULES, rsync project. An exclude rule keeps a file out of the transfer; a protect rule keeps the receiving side from deleting a file that is not in the sender’s list. ↩︎↩︎
-
rsync(1) manpage:
--delete, rsync project. Files excluded from the transfer are also excluded from deletion unless--delete-excludedis used. ↩︎ -
Core functionality: include, nginx documentation. It pulls another file into the configuration and works in any context. ↩︎
-
Module ngx_http_autoindex_module, nginx documentation. With
autoindex on, a request for a folder that has no index file gets a generated directory listing. The default is off. ↩︎ -
Module ngx_http_core_module: try_files, nginx documentation. It checks the listed paths in order and serves the first one that exists; the page’s own example includes
$uri.html. ↩︎ -
Command-line parameters, nginx documentation.
-tchecks the configuration syntax and tries to open the files it refers to. ↩︎