compose-anything/.github/instructions/Guidelines.instructions.md

applyTo

applyTo
**

Compose Anything represents a collection of high-quality, production-ready, and portable Docker Compose configuration files. The primary objective is to allow users to deploy services "out-of-the-box" with minimal configuration while maintaining industry best practices.

The architecture focuses on modularity, security, and orchestrator compatibility (e.g., easy migration to Kubernetes). The technical challenge lies in balancing simplicity (zero-config startup) with robustness (resource limits, health checks, multi-arch support, and security baselines).

Constraints

1. Out-of-the-box
   • Configurations should work out-of-the-box with no extra steps (at most, provide a .env file).
2. Simple commands
   • Each project ships a single docker-compose.yaml file.
   • Command complexity should not exceed docker compose up -d; if more is needed, provide a Makefile.
   • For initialization, prefer healthcheck with depends_on using condition: service_healthy to orchestrate startup order.
3. Stable versions
   • Pin to the latest stable version instead of latest.
   • Expose image versions via environment variables (e.g., FOO_VERSION).
4. Configuration conventions
   • Prefer environment variables over complex CLI flags;
   • Pass secrets via env vars or mounted files, never hardcode;
   • Provide sensible defaults to enable zero-config startup;
   • A commented .env.example is required;
   • Env var naming: UPPER_SNAKE_CASE with service prefix (e.g., POSTGRES_*); use *_PORT_OVERRIDE for host port overrides.
5. Profiles
   • Use Profiles for optional components/dependencies;
   • Recommended names: gpu (acceleration), metrics (observability/exporters), dev (dev-only features).
6. Cross-platform & architectures
   • Where images support it, ensure Debian 12+/Ubuntu 22.04+, Windows 10+, macOS 12+ work;
   • Support x86-64 and ARM64 as consistently as possible;
   • Avoid Linux-only host paths like /etc/localtime and /etc/timezone; prefer TZ env var for time zone.
7. Volumes & mounts
   • Prefer relative paths for configuration to improve portability;
   • Prefer named volumes for data directories to avoid permission/compat issues of host paths;
   • If host paths are necessary, provide a top-level directory variable (e.g., DATA_DIR).
8. Resources & logging
   • Always limit CPU and memory to prevent resource exhaustion;
   • For GPU services, enable a single GPU by default via deploy.resources.reservations.devices (maps to device requests) or gpus where applicable;
   • Limit logs (json-file driver: max-size/max-file).
9. Healthchecks
   • Every service should define a healthcheck with suitable interval, timeout, retries, and start_period;
   • Use depends_on.condition: service_healthy for dependency chains.
10. Security baseline (apply when possible)
    • Run as non-root (expose PUID/PGID or set user: "1000:1000");
    • Read-only root filesystem (read_only: true), use tmpfs/writable mounts for required paths;
    • Least privilege: cap_drop: ["ALL"], add back only what’s needed via cap_add;
    • Avoid container_name (hurts scaling and reusable network aliases);
    • If exposing Docker socket or other high-risk mounts, clearly document risks and alternatives.
11. Documentation & Discoverability
    • Provide clear docs and examples (include admin/initialization notes, and security/license notes when relevant);
    • Keep docs LLM-friendly;
    • List primary env vars and default ports in the README, and link to README.md / README.zh.md.

Reference template: compose-template.yaml in the repo root.

If you want to find image tags, try fetch url like https://hub.docker.com/v2/repositories/library/nginx/tags?page_size=1&ordering=last_updated.

After update all of the services, please update /README.md & /README.zh.md to reflect the changes.

Final Checklist

1. Is .env.example present and fully commented in English?
2. Are CPU/Memory limits applied?
3. Is container_name removed?
4. Are healthcheck and service_healthy conditions correctly implemented?
5. Are the Chinese docs correctly punctuated with spaces between languages?
6. Have the root repository README files been updated to include the new service?

注意：所有中文的文档都使用中文的标点符号，如 “，”、“（）” 等，中文和英文之间要留有空格。对于 Docker Compose 文件和 .env.example 文件中的注释部分，请使用英语而不是中文。请为每个服务提供英文说明 README.md 和中文说明 README.zh.md。