Say what vhost, parallel run and cutover mean

The deployment readme used three pieces of jargon without defining any of them,
which reads as a locked door to anyone doing their first deploy. It now opens
with what each word means, the table of which address serves what at each stage,
and the note that skipping the parallel run is a legitimate choice.

Domain terms stay in CONTEXT.md; these are operational words for this directory,
so they are defined here.
This commit is contained in:
tanshu committed 2026-09-22 23:24:50 +05:30
1 parent 0667110886
commit 041b8b62fe
1 file changed
+27
+27
View File
@@ -3,6 +3,33 @@
Lives here, beside the app it deploys, the way the other apps on this machine do.
It owns the `menu-app` container and the Site's snippet in the shared Caddyfile.
## Words used below
The deployment reads as jargon if you have not done one before, so:
- **web address** — one hostname the web server answers for. Caddy keeps a block
per address; `menu.hopsngrains.com` is one. Older writing calls this a
_vhost_, which just means "virtual host", and `vhost` is the variable name in
`vars/`.
- **parallel run** — putting the app on a second, temporary address
(`menu-new.hopsngrains.com`) while the old site keeps the real one, so the new
one can be checked on a phone without customers seeing it. It needs a DNS
record for the temporary name, because Caddy has to fetch a certificate for it.
- **cutover** — the moment the real address is pointed at the new app instead of
the old nginx container, and that container is stopped. Customers are on the
new app from then on. It is reversible.
| Stage | Address customers use | Address you check |
| ------------- | ---------------------------------- | ------------------------------------- |
| today | `menu.hopsngrains.com` → old nginx | — |
| parallel run | unchanged | `menu-new.hopsngrains.com` → this app |
| after cutover | `menu.hopsngrains.com` → this app | — |
Skipping the parallel run is a legitimate choice: cutover on its own is one
command, one Caddy reload, and a rollback if anything looks wrong. The parallel
run is for finding out that a container will not start, or a font will not load,
without anyone watching.
## What lives where
| Thing | Where |