feat: update Guidelines

README.md

@@ -67,37 +67,50 @@ Compose Anything helps users quickly deploy various services by providing a set
 
 ## Guidelines
 
-1. **Out-of-the-box**: Configurations should work out-of-the-box, requiring no setup to start (at most, provide a `.env` file).
-2. **Simple Commands**
-    - Each project provides a single `docker-compose.yaml` file.
-    - Command complexity should not exceed the `docker compose` command; if it does, provide a `Makefile`.
-    - If a service requires initialization, use `depends_on` to simulate Init containers.
-3. **Stable Versions**
-    - Provide the latest stable image version instead of `latest`.
-    - Allow version configuration via environment variables.
-4. **Highly Configurable**
-    - Prefer configuration via environment variables rather than complex command-line arguments.
-    - Sensitive information like passwords should be passed via environment variables or mounted files, not hardcoded.
-    - Provide reasonable defaults so services can start with zero configuration.
-    - Provide a well-commented `.env.example` file to help users get started quickly.
-    - Use Profiles for optional dependencies.
-5. **Cross-Platform**: (Where supported by the image) Ensure compatibility with major platforms.
-    - Compatibility: Debian 12+/Ubuntu 22.04+, Windows 10+, macOS 12+.
-    - Support multiple architectures where possible, such as x86-64 and ARM64.
-6. **Careful Mounting**
-    - Use relative paths for configuration file mounts to ensure cross-platform compatibility.
-    - Use named volumes for data directories to avoid permission and compatibility issues with host path mounts.
-7. **Default Resource Limits**
-    - Limit CPU and memory usage for each service to prevent accidental resource exhaustion.
-    - Limit log file size to prevent logs from filling up the disk.
-    - For GPU services, enable single GPU by default.
-8. **Comprehensive Documentation**
-    - Provide good documentation and examples to help users get started and understand the configurations.
-    - Clearly explain how to initialize accounts, admin accounts, etc.
-    - Provide security and license notes when necessary.
-    - Offer LLM-friendly documentation for easy querying and understanding by language models.
-9. **Best Practices**: Follow other best practices to ensure security, performance, and maintainability.
+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`.
 
 ## License
 
-MIT License.
+[MIT License](./LICENSE).