feat: add Docker Compose repository guidelines and quick start instructions

.github/instructions/Guidelines.instructions.md

@@ -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`。

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`。

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/<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  |

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/<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 |