feat: add Docker Compose repository guidelines and quick start instructions
This commit is contained in:
Sun-ZhenXing
@@ -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`。
|
||||
@@ -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`。
|
||||
@@ -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/<service>
|
||||
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 |
|
||||
|
||||
+23
-1
@@ -4,6 +4,28 @@
|
||||
|
||||
Compose Anything 通过提供一组高质量的 Docker Compose 配置文件，帮助用户快速部署各种服务。这些配置约束了资源使用，可快速迁移到 K8S 等系统，并且易于理解和修改。
|
||||
|
||||
## 快速开始
|
||||
|
||||
先进入目标服务目录，再使用 Docker Compose 启动：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Sun-ZhenXing/compose-anything.git
|
||||
cd src/<service>
|
||||
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 |
|
||||
|
||||
Reference in New Issue
Block a user