niklas‑stephan.de

Docker compose project README convention (Arcane, all hosts)

Last updated 05/11/2026 · docker, arcane, convention, ai

Every docker compose project under /data/docker/<project>/ on handtrixxx.com, metis, iris (and hestia) should have a top-level README.md with a consistent structure so Arcane users and AI agents can discover what the project does without reading compose.yml.

Deploy-only compose directories (decided 2026-10-28): if a service has a source repo, /data/docker/<project>/ holds only compose.yml, .env (when needed) and README.md - no Dockerfile, source or test files. The compose pulls a prebuilt image (GHCR or Docker Hub); CI in the repo builds and publishes it. Sources live in /data/github/<repo>/. First case: rustysqueezer (ghcr.io/handtrixx/rustysqueezer:latest, Rust; :python fallback), see local-context-compaction. Gotcha: a locally built image pushed with tag :latest silently overwrites the CI image in GHCR - build in CI, not on the host.

Standard sections (template in use since 2026-10-27):

  1. What the project provides (purpose, services, exposed hostnames/ports).
  2. Interfaces it exposes (UIs, APIs, health endpoints, SMTP, registries, etc.).
  3. How AI/agents can access it (API key location e.g. KEY name in /data/ai-persistence/.env only, MCP endpoints, REST API paths) - never actual secrets in the README.

Motivation: Niklas now uses Arcane (docker.handtrixxx.com) for all 4 servers (env ids: 0 handtrixxx.com, iris 92c1bf1c-048e-4b90-b4ae-825bdc78b11d, hestia 0d6bdd05-8f10-440a-b92f-bd7494cdabf5, metis 0edf5644-a455-463c-ae7f-88394db73d12); a uniform README per project makes the Arcane file editor and agent-driven work effective.

Root cause of “file could not be stored” on iris (diagnosed 2026-10-27): the Arcane agent (v2.17.1) runs as uid/gid 65532 unless PUID/PGID are set; /data/docker on iris (and metis) is owned by handtrixxx (1000) with 0755/0775, so every workspace save fails at BackupProjectDirectory -> acfs.MkdirTemp("/data/docker", "/", ".project-update-backup-*") with mkdirat .: permission denied (HTTP 500 {"detail":"internal error"}). The manager on handtrixxx.com works because its compose sets PUID=1000/PGID=1000. Fix (applied 2026-10-27, verified): PUID=1000/PGID=1000 added to the agent compose on iris, metis and hestia; agent logs now show puid=1000 pgid=1000 and the recurring templates/variables 500s stopped. READMEs seeded for all 10 iris projects directly on disk (uid 1000-owned); portal save still to be re-tested by Niklas.

Status (2026-10-27): all 34 compose projects under /data/docker/ on handtrixxx.com now have a top-level README.md in the template style (what it provides / interfaces / how AI-agents access). Remaining: metis, iris (seeded), hestia projects still need READMEs. stats.handtrixxx.com also has a legacy one-line Readme.md (console snippet) alongside the new README.

Status (2026-10-27): READMEs complete on all four servers - handtrixxx.com 34/34, iris 10/10 (seeded earlier, Arcane header + sections), metis 5/5 (llama, tailscale, backrest, wolf, arcane-agent), hestia 4/4 (restic-server, backrest, tailscale, arcane-agent). hestia SSH: since 2026-10-27 it is a full mesh member (all servers’ + ThinkPad keys installed, ssh hestia alias everywhere; see homelab-server-inventory), so run hestia tasks directly from any host.

Source: Wiki.js