new compose + deploy standard: generic compose, deploy injects identity

Supersedes the prior 'name everything after the repo' guidance, which caused
container-name collisions at fleet scale. The dev's compose now names nothing
repo-specific; the deploy layer injects identity and host paths.

deploy.md:
- replace the 'One name everywhere' danger callout with 'Your compose names
  nothing repo-specific' (no container_name, no hardcoded names/paths)
- rewrite the compose example to the standard: svc service key,
  restart: unless-stopped (required — host unit is oneshot), host paths via
  ${LOGS_DIR}/${CONFIG_DIR}/${MOUNTS_DIR} with :-./ local fallbacks, bare
  'cache' volume. Keep user: "1337:1337" + HOME=/tmp (the services account
  identity — not repo-specific)
- add 'How deploy fills it in' (injected env vars a dev can rely on + the
  resulting docker ps names) and 'Onboarding a service' (deploy <host>
  <workspace> <git-url> [name], deploy key handled via Gitea API)
- update paths to <name>, subprocess example to svc, checklist to the new
  rules; drop docker CLI from secret rotation (host-side edit, we restart)

standards.md:
- add a 'Service compose' section: short convention + Right/Wrong tabs
  (the nova before/after), linking to the Deploy guide for the full detail

Kept the services-account (1337) section and uid-agnostic Dockerfile notes.
Verified in-browser; mkdocs build --strict clean (cross-ref anchor resolves).

Signed-off-by: disqualifier <dev@disqualifier.me>
This commit is contained in:
2026-07-01 01:04:44 -04:00
parent 17b2888c1f
commit 7ed388c69c
2 changed files with 142 additions and 61 deletions
+40
View File
@@ -129,3 +129,43 @@ TimeoutError: request timed out after 30s
Libraries **emit only** — `log = logging.getLogger(__name__)` and nothing
else. Handlers, levels, and formatting are configured once at the
application entry point, so a lib never dictates how its host logs.
## Service compose
A deployable service ships a `compose.yaml` that names **nothing repo-specific** —
the deploy layer injects identity and host paths. See the
[Deploy guide](deploy.md#your-composeyaml) for the full convention and the variables
you can rely on. The short version:
=== "Right"
```yaml
services:
svc:
user: "1337:1337"
restart: unless-stopped
volumes:
- ${LOGS_DIR:-./logs}:/app/logs
- profile:/app/profile
volumes:
profile:
```
=== "Wrong (causes collisions)"
```yaml
services:
nova:
container_name: nova # repo-specific name -> collides
volumes:
- /srv/logs/ricky/nova:/app/logs # hardcoded host path
- nova_profile:/app/profile # repo-prefixed volume
volumes:
nova_profile:
```
Generic service key `svc`, no `container_name`, host paths from `${...}` variables,
and **bare** volume names — that's what makes a service collision-proof on the
fleet.