Say how a site moves between stacks, in one place

The pieces existed across three pages and nothing connected them, so "can we go
from IIS to Docker" had no answer to point at. It is a fair question with a
short answer: the application keeps state in exactly two places, the database
and the instance directory, and nothing is encrypted at rest with SECRET_KEY or
JWT_SECRET_KEY, so a move is a dump plus a directory copy. The schema is
identical across topologies.

What the page spends its length on is the part that is NOT the data, because
that is where the time goes. The server address is baked into things that are
not the server: GE-Enforce manifests, the generated collector script, the
printer client scripts, and printed QR codes, which cannot be swept at all.
Keeping the hostname and repointing DNS makes the migration invisible to the
fleet; changing it does not.

Three other traps, each of which has a symptom that shows up later rather than
at cutover: an aliased IIS site needs MOUNT_PATH and a dist built for that
subpath, while the image builds for the root; an older dump can carry latin1 or
3-byte utf8 table definitions that load quietly into a utf8mb4 server and only
misbehave on the first accented name; and a restored instance directory needs
chown, because docker cp writes under the copying user's uid and the container
runs as shopdb.

Covers both directions plus Docker to a new Docker host, and ends with a cutover
checklist that leaves the old stack stopped rather than removed until a bay has
checked in on a working day.

Also fixes two links in START-HERE that pointed at files which are not there:
the ADR index needed its adr/ prefix, and LLM-GUIDE.md is llms.txt.
This commit is contained in:
cproudlock
2026-08-19 19:51:02 -04:00
parent 417f8a3dd4
commit a7f5d2d0bf
2 changed files with 221 additions and 2 deletions

View File

@@ -43,7 +43,7 @@ artifact comes from.
## I am integrating with the API
1. [LLM-GUIDE](LLM-GUIDE.md) (`docs/llms.txt` in the repo, also served at
1. [LLM-GUIDE](llms.txt) (`docs/llms.txt` in the repo, also served at
`/api/docs/llms.txt`) - auth, the response envelope, common recipes.
Short, and the envelope section is the part people get wrong.
2. `GET /api/docs` on any running instance - the full spec, browsable.
@@ -52,7 +52,7 @@ artifact comes from.
## I am trying to understand why something is built this way
[The ADRs](ADR-001-asset-as-platform-contract.md). They are the decision record,
[The ADRs](adr/ADR-001-asset-as-platform-contract.md). They are the decision record,
they say what was rejected and why, and they are the fastest way to avoid
relitigating a settled question. [PROJECT-MAP](PROJECT-MAP.md) lists them all
with their status, along with the current versions and every migration head -
@@ -65,3 +65,8 @@ it is generated, so it is never stale.
[FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) says which piece to open first.
- A deploy that half-worked: [UPGRADE](UPGRADE.md) and
[BACKUP-RESTORE](BACKUP-RESTORE.md).
## I am moving a site to a different server or stack
[MIGRATE-TOPOLOGY](MIGRATE-TOPOLOGY.md) - Windows/IIS to Docker, Docker to a new
host, and back. The data moves cleanly; the URL the fleet points at is the work.