70 lines
4.6 KiB
Markdown
70 lines
4.6 KiB
Markdown
---
|
||
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`](../../.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`。
|