From 17b2888c1f4a0d878fdcc0da6f87105e6877b49f Mon Sep 17 00:00:00 2001 From: disqualifier Date: Tue, 30 Jun 2026 23:13:35 -0400 Subject: [PATCH] =?UTF-8?q?deploy:=20red=20callout=20=E2=80=94=20repo=20na?= =?UTF-8?q?me=20must=20match=20container=20+=20volume=20names?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a prominent danger admonition ('One name everywhere — repo = container = volumes') right under the intro: the repo name is the name; the compose service key, container_name, and every named volume must all use it. Spell out the consequence — mismatched names break deploy, monitoring, and log scraping, which key off the repo name. Make the compose example teach it: rename yourapp -> myrepo throughout (service key, container_name: myrepo, myrepo-data volume) with annotations calling out each spot where the repo name must appear. Verified in-browser; mkdocs build --strict clean. Signed-off-by: disqualifier --- docs/deploy.md | 41 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/docs/deploy.md b/docs/deploy.md index 8e34e9e..d924762 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -7,6 +7,18 @@ !!! tip "What can run here" APIs, websites, applets, bots, monitors. +!!! danger "One name everywhere — repo = container = volumes" + The **repo name is the name.** Your service (the compose service key), the + container, and every named volume **must all use that same name**. If your repo + is `myrepo`: + + - service → `myrepo` + - container → `myrepo` + - volumes → `myrepo-data`, `myrepo-cache`, … (the repo name, then a suffix) + + Mismatched names break our deploy, monitoring, and log scraping — they key off + the repo name. **Do not** name the service one thing and the repo another. + ## Docker — the services account Every service runs containerized as the shared **`services`** account: @@ -66,28 +78,35 @@ CMD ["python", "-m", "yourapp"] 3. `--system` installs into the image's Python (no venv needed — the container *is* the isolation); reads `pyproject.toml`, no `uv.lock` required. +The service key, `container_name`, and volume names below are all **`myrepo`** — +the repo name. Match yours to your repo. + ```yaml services: - yourapp: + myrepo: # (1)! build: . - user: "1337:1337" # (1)! + container_name: myrepo # (2)! + user: "1337:1337" # (3)! environment: HOME: /tmp volumes: - - /srv/config//:/app/config:ro # (2)! - - /srv/logs//:/app/logs # (3)! - - yourapp-data:/app/data # (4)! + - /srv/config//:/app/config:ro # (4)! + - /srv/logs//:/app/logs # (5)! + - myrepo-data:/app/data # (6)! volumes: - yourapp-data: + myrepo-data: # (7)! ``` -1. Run as the shared account. **No** in-container `user`/`useradd` — don't bake a +1. Service key = **the repo name**. +2. Container name = **the repo name** — same as the service. +3. Run as the shared account. **No** in-container `user`/`useradd` — don't bake a user into the image; set it here. -2. Configs: host-managed bind mount, mounted **read-only**. -3. Logs: bind mount — live and rolled, scraped for monitoring. -4. Everything else: a **named volume**. Docker owns it, so there are no host - permissions to fiddle with. +4. Config: host-managed bind mount, mounted **read-only**. +5. Logs: bind mount — live and rolled, scraped for monitoring. +6. Named volume = **repo name + suffix** (`myrepo-data`). Docker owns it, so there + are no host permissions to fiddle with. +7. Declare the volume under the same **repo-name-prefixed** key. ## Paths and mounts