From 41c4e8fd4e41f7ed25965a438b166f73a11819d0 Mon Sep 17 00:00:00 2001 From: Sun-ZhenXing <1006925066@qq.com> Date: Sat, 11 Apr 2026 23:05:35 +0800 Subject: [PATCH] feat: add Docker Compose repository guidelines and quick start instructions --- .../instructions/Guidelines.instructions.md | 69 --------------- AGENTS.md | 85 +++++++++++++++++++ README.md | 24 +++++- README.zh.md | 24 +++++- 4 files changed, 131 insertions(+), 71 deletions(-) delete mode 100644 .github/instructions/Guidelines.instructions.md create mode 100644 AGENTS.md diff --git a/.github/instructions/Guidelines.instructions.md b/.github/instructions/Guidelines.instructions.md deleted file mode 100644 index 4a52a21..0000000 --- a/.github/instructions/Guidelines.instructions.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -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`。 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6fca356 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,85 @@ +# 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`。 diff --git a/README.md b/README.md index f6980a1..ed0f476 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,28 @@ Compose Anything helps users quickly deploy various services by providing a set of high-quality Docker Compose configuration files. These configurations constrain resource usage, can be easily migrated to systems like K8S, and are easy to understand and modify. +## Quick Start + +Choose a service directory, then start it with Docker Compose: + +```bash +git clone https://github.com/Sun-ZhenXing/compose-anything.git +cd src/ +docker compose up -d +``` + +Most stacks are designed to run with the default settings. Use `.env.example` as a reference, and only create a `.env` file when you need to override ports, passwords, or image versions. + +### Example: Start Redis + +```bash +cd src/redis +docker compose up -d +docker compose exec redis redis-cli ping +``` + +If the stack is healthy, the final command returns `PONG`. By default, Redis is exposed on `localhost:6379`. For authentication, custom ports, or image changes, see [src/redis](./src/redis). + ## Build Services These services require building custom Docker images from source. @@ -190,7 +212,7 @@ These services require building custom Docker images from source. | [OpenWeather](./mcp-servers/openweather) | latest | | [Paper Search](./mcp-servers/paper-search) | latest | | [Playwright](./mcp-servers/playwright) | latest | -| [Redis MCP](./mcp-servers/redis-mcp) | latest | +| [Redis MCP](./mcp-servers/redis) | latest | | [Rust Filesystem](./mcp-servers/rust-mcp-filesystem) | latest | | [Sequential Thinking](./mcp-servers/sequentialthinking) | latest | | [SQLite](./mcp-servers/sqlite) | latest | diff --git a/README.zh.md b/README.zh.md index c3cddc0..bfbf237 100644 --- a/README.zh.md +++ b/README.zh.md @@ -4,6 +4,28 @@ Compose Anything 通过提供一组高质量的 Docker Compose 配置文件，帮助用户快速部署各种服务。这些配置约束了资源使用，可快速迁移到 K8S 等系统，并且易于理解和修改。 +## 快速开始 + +先进入目标服务目录，再使用 Docker Compose 启动： + +```bash +git clone https://github.com/Sun-ZhenXing/compose-anything.git +cd src/ +docker compose up -d +``` + +大多数配置都可以直接使用默认值启动。`.env.example` 用于说明可选配置项；只有在你需要覆盖端口、密码或镜像版本时，才需要额外创建 `.env` 文件。 + +### 示例：快速启动 Redis + +```bash +cd src/redis +docker compose up -d +docker compose exec redis redis-cli ping +``` + +如果服务正常，最后一条命令会返回 `PONG`。默认情况下，Redis 会暴露在 `localhost:6379`。如果需要认证、自定义端口或调整镜像版本，请查看 [src/redis](./src/redis)。 + ## 构建服务 这些服务需要从源代码构建自定义 Docker 镜像。 @@ -190,7 +212,7 @@ Compose Anything 通过提供一组高质量的 Docker Compose 配置文件， | [OpenWeather](./mcp-servers/openweather) | latest | | [Paper Search](./mcp-servers/paper-search) | latest | | [Playwright](./mcp-servers/playwright) | latest | -| [Redis MCP](./mcp-servers/redis-mcp) | latest | +| [Redis MCP](./mcp-servers/redis) | latest | | [Rust Filesystem](./mcp-servers/rust-mcp-filesystem) | latest | | [Sequential Thinking](./mcp-servers/sequentialthinking) | latest | | [SQLite](./mcp-servers/sqlite) | latest |