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.

Topic rules live in .claude/rules/ and load with this file:

• naming.md — file, directory, service, volume and network names, with example role names for supporting containers.
• images-and-comments.md — where and how software is installed, and what comments in compose files, Dockerfiles and scripts may say.
• workspace-services.md — the home and /workspace volume split for services someone works inside.
• environment-and-secrets.md — environment: order, .env.example, and secrets.

Deployment target

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

Coolify is the primary target: design, test and debug against it first. Dokploy is optional — keep a service working there when it costs nothing (the restart: policy below), but never trade Coolify behaviour for Dokploy compatibility, and do not block on Dokploy-only issues.

Service READMEs stay inside their directory

This rule has high priority: editing one service must never redeploy another. A service's README.md describes that service and nothing else. It does not name, link to, or compare itself with another service, and it does not link up to the root README, CLAUDE.md or .claude/rules/. Shared conventions — the workspace volume split, no published ports, the restart policy, secrets, variable order — are written once at the root and are not restated or "see the root for why"-linked from a service. A service README says what the service is, its variables, storage and wiring, and the reasons behind choices specific to that service. Keep it concise and minimal.

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.

This is a deployment rule, not a style preference. Each service is a separate Coolify app whose webhook watch path is <service>/**. A cross-link means renaming or editing one service touches another's directory and redeploys it. Cross-cutting changes to every compose file (a new restart policy, say) are the one legitimate case where a push redeploys several services.

Every Coolify app created from this repo sets its watch path to <service>/**. After creating one, check watch_paths with the Coolify MCP get_application; null means the app deploys on every push to the repository. Only these are null and expected — do not flag or "fix" them:

• traffmonetizer, on both miti-sg and miti-jp, leaves it unset on purpose to be restarted on every push.

Service directories hold deploy files only

Because of that watch path, every file in a service directory redeploys the service when it changes. A service directory holds only what the deploy reads or what describes it: compose.yml, README.md, .env.example, .gitignore, and any Dockerfile, entrypoint or config file the build or containers use.

• Agent skills for a service — maintenance scripts, runbooks — go in the root .claude/skills/<name>/, never in <service>/.claude/. A skill there also only loads once a session touches that directory.
• Docs beyond the README go in the root docs/<service>/, named exactly like the service directory; renaming a service renames its docs directory in the same commit. The service README.md covers only what the service is and how to deploy it — variables, storage, wiring, and the reasons behind its configuration. Anything issue-related — known problems, log noise, troubleshooting, investigations, upstream research and audits — goes in docs/<service>/. The README does not link there; docs may link to the service.
• Anything else that is not deploy input — CI workflows, test fixtures — has no default home. Ask the user where it goes before adding it to a service directory.

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. Coolify's ports_exposes field (often a prefilled 3000) is never read for compose apps; the proxy port comes from the compose expose: entry or the domain's port. Leave it.
• 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.

restart: is the exception that is not omitted. Every service sets restart: unless-stopped, on every container. Coolify injects that exact value when a service does not declare one, and keeps the declared value when it does; Dokploy does not inject anything, so in its default compose mode an omitted policy leaves the container down after a crash or a host reboot. Setting it is correct on both. traffmonetizer sets restart: always on purpose, to be restarted as often as possible.

Upstream sources

sources/ is for upstream source checkouts used while debugging, cloned as sources/<owner>/<repo> at the version the service runs. Its contents are gitignored; only sources/.gitkeep is tracked. Never commit a checkout or fix a service by editing code there. Use the debug-service skill (.claude/skills/debug-service/SKILL.md) for service issues.