rethink-public/handbook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

deploy: red callout — repo name must match container + volume names

Browse Source 
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 <dev@disqualifier.me>
This commit is contained in:
dsql
2026-06-30 23:13:35 -04:00
parent c53d67da2f
commit 17b2888c1f
1 changed files with 30 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deploy.md
+30 -11
View File
@@ -7,6 +7,18 @@
!!! tip "What can run here" !!! tip "What can run here"
APIs, websites, applets, bots, monitors. 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 ## Docker — the services account
Every service runs containerized as the shared **`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 3. `--system` installs into the image's Python (no venv needed — the container
*is* the isolation); reads `pyproject.toml`, no `uv.lock` required. *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 ```yaml
services: services:
yourapp: myrepo: # (1)!
build: . build: .
user: "1337:1337" # (1)! container_name: myrepo # (2)!
user: "1337:1337" # (3)!
environment: environment:
HOME: /tmp HOME: /tmp
volumes: volumes:
- /srv/config/<workspace>/<project>:/app/config:ro # (2)! - /srv/config/<workspace>/<project>:/app/config:ro # (4)!
- /srv/logs/<workspace>/<project>:/app/logs # (3)! - /srv/logs/<workspace>/<project>:/app/logs # (5)!
- yourapp-data:/app/data # (4)! - myrepo-data:/app/data # (6)!
volumes: 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. user into the image; set it here.
2. Configs: host-managed bind mount, mounted **read-only**. 4. Config: host-managed bind mount, mounted **read-only**.
3. Logs: bind mount — live and rolled, scraped for monitoring. 5. Logs: bind mount — live and rolled, scraped for monitoring.
4. Everything else: a **named volume**. Docker owns it, so there are no host 6. Named volume = **repo name + suffix** (`myrepo-data`). Docker owns it, so there
permissions to fiddle with. are no host permissions to fiddle with.
7. Declare the volume under the same **repo-name-prefixed** key.
## Paths and mounts ## Paths and mounts