# Docker Compose Repository Guidelines

Compose Anything is a collection of production-ready, portable Docker Compose stacks. The default experience should remain simple: users should be able to enter a service directory and start it with `docker compose up -d`, while still getting sensible defaults for resource limits, health checks, security, and documentation.

## Primary Goals

1. Keep every stack easy to start and easy to understand.
2. Prefer portable Compose patterns that work across Windows, macOS, and Linux.
3. Default to production-aware settings instead of demo-only shortcuts.
4. Keep service documentation and root indexes accurate whenever a service changes.

## Required Workflow For Service Changes

1. Read the existing service folder before editing anything.
2. Use the repo root `.compose-template.yaml` as the structural reference when applicable.
3. Update these files together when a service changes: `docker-compose.yaml`, `.env.example`, `README.md`, and `README.zh.md`.
4. Update the root `README.md` and `README.zh.md` whenever a service is added, renamed, removed, or needs a new quick-start entry.
5. Keep the default startup path within `docker compose up -d`. If extra setup is unavoidable, document it clearly and prefer a `Makefile` over ad-hoc instructions.

## Compose Standards

1. Out-of-the-box startup
    - A stack should work with zero extra steps, except optionally creating a `.env` file from `.env.example`.
    - Defaults must be usable for local evaluation without forcing users to edit configuration first.
2. Command simplicity
    - Each project should ship a single `docker-compose.yaml` file.
    - Initialization order should use `healthcheck` plus `depends_on.condition: service_healthy` whenever a dependency chain exists.
3. Version pinning
    - Pin to a stable image version instead of `latest` whenever a stable tag exists.
    - Expose image versions via environment variables such as `REDIS_VERSION` or `POSTGRES_VERSION`.
4. Configuration style
    - Prefer environment variables over long CLI flags.
    - Never hardcode secrets.
    - Provide a fully commented `.env.example` in English.
    - Use UPPER_SNAKE_CASE names with a service prefix.
    - Use `*_PORT_OVERRIDE` for host port overrides.
5. Profiles
    - Use Compose profiles for optional components only.
    - Preferred profile names: `gpu`, `metrics`, `dev`.
6. Cross-platform support
    - Favor patterns that work on Debian 12+, Ubuntu 22.04+, Windows 10+, and macOS 12+ when upstream images support them.
    - Support both x86-64 and ARM64 as consistently as practical.
    - Avoid Linux-only host paths such as `/etc/localtime`; prefer `TZ`.
7. Storage and mounts
    - Prefer named volumes for application data.
    - Prefer relative paths for repo-managed configuration files.
    - If host paths are necessary, expose a top-level directory variable such as `DATA_DIR`.
8. Resources and logging
    - Every service must define CPU and memory limits.
    - GPU services should default to one GPU via `deploy.resources.reservations.devices` or `gpus`.
    - Limit container logs with the `json-file` driver and `max-size` / `max-file`.
9. Health checks
    - Every long-running service should define a meaningful `healthcheck`.
    - Tune `interval`, `timeout`, `retries`, and `start_period` for the actual startup profile of the service.
10. Security baseline
    - Run as non-root when practical.
    - Use `read_only: true` plus writable mounts or `tmpfs` where feasible.
    - Default to `cap_drop: ["ALL"]` and add back only what is required.
    - Do not use `container_name`.
    - If a stack requires the Docker socket or another high-risk mount, document the risk and safer alternatives.

## Documentation Standards

1. Every service must provide both `README.md` and `README.zh.md`.
2. Service READMEs should at minimum cover: purpose, services, quick start, key environment variables, storage, and security notes when relevant.
3. The root `README.md` and `README.zh.md` should remain useful as entry points, not just service indexes. Include concise quick-start guidance and at least one concrete example when it helps discovery.
4. List the main environment variables and default ports in the service README.
5. Keep documentation LLM-friendly: predictable headings, short paragraphs, and concrete command examples.

Reference template: `/.compose-template.yaml`

If you need image tags, check the Docker Hub API, for example:
`https://hub.docker.com/v2/repositories/library/nginx/tags?page_size=1&ordering=last_updated`

## Final Checklist

1. Is `.env.example` present and fully commented in English?
2. Are CPU and memory limits defined?
3. Has `container_name` been avoided or removed?
4. Are `healthcheck` and `depends_on.condition: service_healthy` used correctly?
5. Are `README.md` and `README.zh.md` both updated for the service?
6. Are the root `README.md` and `README.zh.md` updated if discoverability changed?
7. Are Chinese docs using Chinese punctuation, with spaces between Chinese and English terms?

**注意**：所有中文文档都使用中文标点，如 “，”、“（）” 等，中文与英文之间保留空格。Docker Compose 文件和 `.env.example` 文件中的注释必须使用英文。每个服务都必须提供英文 `README.md` 和中文 `README.zh.md`。