composes/CLAUDE.md

composes

Personal docker compose collection. One directory per service, each holding compose.yml, its own README.md, a committed .env.example, and a gitignored .env.

File naming

New services use compose.yml — the current Compose spec name, and the shorter one. Existing services that still use docker-compose.yml stay as they are; do not rename them, not even while touching the file for something else.

Installing software in an image

Follow the upstream project's own documented install method, or the one the community has settled on. In order of preference: the vendor's signed package repository, the vendor's official tarball or install script, then a well-known community installer. Do not hand-roll a download, and do not take a stale distro package just because apt install is shorter — check what version it actually gives you first.

Comments in compose files, Dockerfiles and scripts

This holds for every file in a service directory, not just the compose file.

A comment says what a section installs, configures or does, in a line or two. It does not explain why. Reasons — why not the distro package, why that directory, why a version is pinned, why a step runs here and not there, what would break if it were simplified — go in the service's README.md, where they can be read in full and where someone deciding whether to change something will actually look.

So: no rationale, no trade-offs, no cautionary notes in the file itself. When a choice needs defending, write the defence in the README and let the header comment point at it. Keep the README current whenever a file changes, otherwise the reasoning is simply lost rather than relocated.

The root README.md is an index only — it covers the shared conventions and links out to each service. Per-service detail (variables, ports, storage) belongs in that service's README, not the root one. Adding a service means adding its README and a row to the root table.

Deployment target

Services are deployed through Coolify and Dokploy, not plain docker compose on a host. The platform owns the parts a standalone compose file would declare itself.

Intentional omissions — do not "fix" these

These are deliberate, not oversights. Do not flag them as defects or add them unprompted:

• No ports:. Coolify and Dokploy attach the container to their proxy network and map a domain to the internal port. Publishing a port is redundant and would additionally expose it on the host.
• No restart: policy. The platform manages the container lifecycle.
• No container_name:. Let Compose derive it from the directory.

More generally: these files are tuned to one person's setup and are not meant to be portable, standard, or turnkey. Prefer leaving a service minimal over adding hardening or convention that the platform already provides.

Secrets

Every service reads secrets from a sibling .env. Never commit one — the root .gitignore covers .env/*.env and re-includes .env.example. Keep .env.example in sync whenever a compose file gains or drops a variable.

.env.example is a template for anyone, so every value in it stays generic — the service's own name, a placeholder domain, or an empty string. Never a real hostname, git identity, email, domain or account name. Personal values are set per deployment, in the Coolify or Dokploy environment for that app, and live only in the gitignored .env.

Compose interpolation reads the deploying shell's environment before the .env file, so a variable must not share a name with anything the shell already exports. HOSTNAME is the trap: it is set inside every container, including the one Coolify itself runs in, and would silently win. Hence SERVICE_HOSTNAME in code-server and paseo.