diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..72789df --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "yzhang.markdown-all-in-one", + "DavidAnson.vscode-markdownlint" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..8c0a364 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,18 @@ +{ + "prettier.enable": false, + "editor.formatOnSave": false, + "[markdown]": { + "editor.wordWrap": "on", + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll.markdownlint": "explicit" + }, + "editor.quickSuggestions": { + "other": "off", + "comments": "off", + "strings": "off" + } + }, + "files.eol": "\n", + "cSpell.enabled": false +} diff --git a/README.md b/README.md index f5937c3..3050708 100644 --- a/README.md +++ b/README.md @@ -1 +1,46 @@ # Compose Anything + +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. + +## Supported Services + +| Service | Version | +| -------------------- | ------- | +| [Redis](./src/redis) | 8.2.1 | + +## 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. + +## License + +MIT License. diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 0000000..71acb81 --- /dev/null +++ b/README.zh.md @@ -0,0 +1,46 @@ +# Compose Anything + +Compose Anything 通过提供一组高质量的 Docker Compose 配置文件,帮助用户快速部署各种服务。这些配置约束了资源使用,可快速迁移到 K8S 等系统,并且易于理解和修改。 + +## 已经支持的服务 + +| 服务 | 版本 | +| -------------------- | ----- | +| [Redis](./src/redis) | 8.2.1 | + +## 规范 + +1. **开箱即用**,配置应该是开箱即用的,无需配置也能启动(最多提供 `.env` 文件); +2. **命令简单** + - 每个项目提供单一的 `docker-compose.yaml` 文件; + - 命令的复杂性避免超过 `docker compose` 命令,如果超过请提供 `Makefile`; + - 如果服务需要初始化,可借助 `depends_on` 模拟 Init 容器; +3. **版本稳定** + - 提供一个最新稳定的镜像版本而不是 `latest`; + - 允许通过环境变量配置版本号; +4. **充分可配置** + - 尽量通过环境变量配置,而不是通过复杂的命令行参数; + - 环境变量,密码等敏感信息应通过环境变量或挂载文件传递,不要硬编码; + - 提供合理默认值,尽量零配置能启动; + - 尽可能提供 `.env.example` 文件并有注释,帮助用户快速上手; + - 如果是非必要依赖,请使用 Profiles 配置; +5. **跨平台**,(在镜像支持的情况下)请确保主流平台都能正常启动; + - 兼容标准是:Debian 12+/Ubuntu 22.04+、Windows 10+、macOS 12+; + - 尽可能兼容不同的架构,如 x86-64、ARM64; +6. **小心处理挂载** + - 配置文件尽量使用相对路径挂载,确保跨平台兼容性; + - 数据目录尽量使用命名卷,避免主机路径挂载带来的权限和兼容性问题; +7. **默认资源限制** + - 对每个服务限制 CPU 和内存使用,防止意外的资源耗尽; + - 限制日志的大小,防止日志文件占满磁盘; + - 对于 GPU 服务默认启用单卡; +8. **文档全面** + - 提供良好的文档和示例,帮助用户快速上手和理解配置; + - 特别要提供如何初始化账户,管理员账户等说明; + - 必要时,提供安全和许可说明; + - 提供 LLM 友好的文档,方便用户使用 LLM 进行查询和理解; +9. **最佳实践**,遵循其他可能的最佳实践,确保安全性、性能和可维护性。 + +## 开源协议 + +MIT License. diff --git a/src/redis/.env.example b/src/redis/.env.example new file mode 100644 index 0000000..2f6ad73 --- /dev/null +++ b/src/redis/.env.example @@ -0,0 +1,11 @@ +# App version +REDIS_VERSION="8.2.1-alpine3.22" + +# Skip fixing permissions, set to 1 to skip +SKIP_FIX_PERMS=1 + +# Password for the default "default" user +REDIS_PASSWORD="passw0rd" + +# Port to bind to on the host machine +REDIS_PORT_OVERRIDE_6379=16379 diff --git a/src/redis/README.md b/src/redis/README.md new file mode 100644 index 0000000..c93daaa --- /dev/null +++ b/src/redis/README.md @@ -0,0 +1,12 @@ +# Redis + +## Environment Variables + +| Variable Name | Description | Default Value | +| ------------------------ | -------------------------------------------------------- | -------------------- | +| REDIS_VERSION | Redis image version | `"8.2.1-alpine3.22"` | +| SKIP_FIX_PERMS | Skip permission fixing, set to 1 to skip | `""` | +| REDIS_PASSWORD | Password for the default "default" user | `""` | +| REDIS_PORT_OVERRIDE_6379 | Host port mapping (maps to Redis port 6379 in container) | 6379 | + +Please modify the `.env` file as needed for your use case. diff --git a/src/redis/docker-compose.yaml b/src/redis/docker-compose.yaml new file mode 100644 index 0000000..79f8e8f --- /dev/null +++ b/src/redis/docker-compose.yaml @@ -0,0 +1,41 @@ +x-default: &default + restart: unless-stopped + volumes: + - &localtime /etc/localtime:/etc/localtime:ro + - &timezone /etc/timezone:/etc/timezone:ro + logging: + driver: json-file + options: + max-size: 100m + +services: + redis: + <<: *default + image: redis:${REDIS_VERSION:-8.2.1-alpine3.22} + container_name: redis + ports: + - "${REDIS_PORT_OVERRIDE_6379:-6379}:6379" + volumes: + - *localtime + - *timezone + - redis_data:/data + + # !! Uncomment to use a custom redis.conf file + # - ./redis.conf:/etc/redis/redis.conf + environment: + - SKIP_FIX_PERMS=${SKIP_FIX_PERMS:-} + command: + - redis-server + - --requirepass + - ${REDIS_PASSWORD:-} + deploy: + resources: + limits: + cpus: '0.50' + memory: 512M + reservations: + cpus: '0.25' + memory: 256M + +volumes: + redis_data: