From 953bb146ba8ad5d4f7e8303362ed471c585e67a4 Mon Sep 17 00:00:00 2001 From: Sun-ZhenXing <1006925066@qq.com> Date: Mon, 29 Dec 2025 18:05:34 +0800 Subject: [PATCH] feat: add libsql --- README.md | 409 +++++++++--------- README.zh.md | 409 +++++++++--------- builds/debian-dind/.env.example | 4 +- builds/debian-dind/Dockerfile | 2 +- builds/debian-dind/README.md | 22 +- builds/debian-dind/README.zh.md | 22 +- builds/debian-dind/docker-compose.yaml | 12 +- builds/debian-dind/dockerd-entrypoint.sh | 70 +-- builds/kata-inside-dind/.env.example | 2 +- builds/kata-inside-dind/Dockerfile | 5 +- builds/kata-inside-dind/README.md | 24 +- builds/kata-inside-dind/README.zh.md | 24 +- builds/kata-inside-dind/docker-compose.yaml | 2 +- builds/kata-inside-dind/dockerd-entrypoint.sh | 9 + src/libsql/.env.example | 71 +++ src/libsql/README.md | 228 ++++++++++ src/libsql/README.zh.md | 228 ++++++++++ src/libsql/docker-compose.yaml | 87 ++++ 18 files changed, 1128 insertions(+), 502 deletions(-) create mode 100644 src/libsql/.env.example create mode 100644 src/libsql/README.md create mode 100644 src/libsql/README.zh.md create mode 100644 src/libsql/docker-compose.yaml diff --git a/README.md b/README.md index 0ea3edd..9f1d7a7 100644 --- a/README.md +++ b/README.md @@ -1,204 +1,205 @@ -# 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 | -| ------------------------------------------------------------- | ---------------------------- | -| [Apache APISIX](./src/apisix) | 3.13.0 | -| [Apache Cassandra](./src/cassandra) | 5.0.2 | -| [Apache Flink](./src/flink) | 1.20.0 | -| [Apache HBase](./src/hbase) | 2.6 | -| [Apache HTTP Server](./src/apache) | 2.4.62 | -| [Apache Kafka](./src/kafka) | 7.8.0 | -| [Apache Pulsar](./src/pulsar) | 4.0.7 | -| [Apache RocketMQ](./src/rocketmq) | 5.3.1 | -| [Bifrost Gateway](./src/bifrost-gateway) | 1.3.48 | -| [Bolt.diy](./src/bolt-diy) | latest | -| [Budibase](./src/budibase) | 3.23.0 | -| [Bytebot](./src/bytebot) | edge | -| [Clash](./src/clash) | 1.18.0 | -| [ClickHouse](./src/clickhouse) | 24.11.1 | -| [Conductor](./src/conductor) | latest | -| [Dify](./src/dify) | 0.18.2 | -| [DNSMasq](./src/dnsmasq) | 2.91 | -| [Dockge](./src/dockge) | 1 | -| [Docker Registry](./src/docker-registry) | 3.0.0 | -| [DuckDB](./src/duckdb) | v1.1.3 | -| [Easy Dataset](./src/easy-dataset) | 1.5.1 | -| [Elasticsearch](./src/elasticsearch) | 8.16.1 | -| [etcd](./src/etcd) | 3.6.0 | -| [Firecrawl](./src/firecrawl) | latest | -| [frpc](./src/frpc) | 0.64.0 | -| [frps](./src/frps) | 0.64.0 | -| [Gitea Runner](./src/gitea-runner) | 0.2.13 | -| [Gitea](./src/gitea) | 1.24.6 | -| [GitLab Runner](./src/gitlab-runner) | 17.10.1 | -| [GitLab](./src/gitlab) | 17.10.4-ce.0 | -| [GPUStack](./src/gpustack) | v0.5.3 | -| [Grafana](./src/grafana) | 12.1.1 | -| [Halo](./src/halo) | 2.21.9 | -| [Harbor](./src/harbor) | v2.12.0 | -| [HashiCorp Consul](./src/consul) | 1.20.3 | -| [IOPaint](./builds/io-paint) | latest | -| [Jenkins](./src/jenkins) | 2.486-lts | -| [JODConverter](./src/jodconverter) | latest | -| [Kestra](./src/kestra) | latest-full | -| [Kibana](./src/kibana) | 8.16.1 | -| [Kodbox](./src/kodbox) | 1.62 | -| [Kong](./src/kong) | 3.8.0 | -| [Langflow](./apps/langflow) | latest | -| [Langfuse](./apps/langfuse) | 3.115.0 | -| [LibreOffice](./src/libreoffice) | latest | -| [LiteLLM](./src/litellm) | main-stable | -| [Logstash](./src/logstash) | 8.16.1 | -| [MariaDB Galera Cluster](./src/mariadb-galera) | 11.7.2 | -| [Milvus Standalone Embed](./src/milvus-standalone-embed) | 2.6.2 | -| [Milvus Standalone](./src/milvus-standalone) | 2.6.2 | -| [Minecraft Bedrock Server](./src/minecraft-bedrock-server) | latest | -| [MinerU SGLang](./src/mineru-sglang) | 2.2.2 | -| [MinerU vLLM](./builds/mineru-vllm) | 2.6.4 | -| [MinIO](./src/minio) | RELEASE.2025-09-07T16-13-09Z | -| [MLflow](./src/mlflow) | v2.20.2 | -| [MongoDB ReplicaSet Single](./src/mongodb-replicaset-single) | 8.0.13 | -| [MongoDB ReplicaSet](./src/mongodb-replicaset) | 8.0.13 | -| [MongoDB Standalone](./src/mongodb-standalone) | 8.0.13 | -| [MySQL](./src/mysql) | 9.4.0 | -| [n8n](./src/n8n) | 1.114.0 | -| [Nacos](./src/nacos) | v3.1.0 | -| [NebulaGraph](./src/nebulagraph) | v3.8.0 | -| [NexaSDK](./src/nexa-sdk) | v0.2.62 | -| [Neo4j](./src/neo4j) | 5.27.4 | -| [Netdata](./src/netdata) | latest | -| [Nginx](./src/nginx) | 1.29.1 | -| [Node Exporter](./src/node-exporter) | v1.8.2 | -| [OceanBase](./src/oceanbase) | 4.3.3 | -| [Odoo](./src/odoo) | 19.0 | -| [Ollama](./src/ollama) | 0.12.0 | -| [Open WebUI](./src/open-webui) | main | -| [Phoenix (Arize)](./src/phoenix) | 12.19.0 | -| [Pingora Proxy Manager](./src/pingora-proxy-manager) | v1.0.3 | -| [Open WebUI Rust](./src/open-webui-rust) | latest | -| [OpenCoze](./src/opencoze) | See Docs | -| [OpenCut](./src/opencut) | latest | -| [OpenList](./src/openlist) | latest | -| [OpenSearch](./src/opensearch) | 2.19.0 | -| [PocketBase](./src/pocketbase) | 0.30.0 | -| [Portainer](./src/portainer) | 2.27.3-alpine | -| [Portkey AI Gateway](./src/portkey-gateway) | latest | -| [PostgreSQL](./src/postgres) | 17.6 | -| [Prometheus](./src/prometheus) | 3.5.0 | -| [PyTorch](./src/pytorch) | 2.6.0 | -| [Qdrant](./src/qdrant) | 1.15.4 | -| [RabbitMQ](./src/rabbitmq) | 4.1.4 | -| [Ray](./src/ray) | 2.42.1 | -| [Redpanda](./src/redpanda) | v24.3.1 | -| [Redis Cluster](./src/redis-cluster) | 8.2.1 | -| [Redis](./src/redis) | 8.2.1 | -| [Renovate](./src/renovate) | 42.52.5-full | -| [Restate Cluster](./src/restate-cluster) | 1.5.3 | -| [Restate](./src/restate) | 1.5.3 | -| [SearXNG](./src/searxng) | 2025.1.20-1ce14ef99 | -| [Sim](./apps/sim) | latest | -| [Stable Diffusion WebUI](./src/stable-diffusion-webui-docker) | latest | -| [Stirling-PDF](./src/stirling-pdf) | latest | -| [Temporal](./src/temporal) | 1.24.2 | -| [TiDB](./src/tidb) | v8.5.0 | -| [TiKV](./src/tikv) | v8.5.0 | -| [Trigger.dev](./src/trigger-dev) | v4.2.0 | -| [TrailBase](./src/trailbase) | 0.22.4 | -| [Valkey Cluster](./src/valkey-cluster) | 8.0 | -| [Valkey](./src/valkey) | 8.0 | -| [Verdaccio](./src/verdaccio) | 6.1.2 | -| [vLLM](./src/vllm) | v0.8.0 | -| [Windmill](./src/windmill) | main | -| [ZooKeeper](./src/zookeeper) | 3.9.3 | - -## MCP Servers - -| Server | Version | -| ------------------------------------------------------- | ------- | -| [API Gateway](./mcp-servers/api-gateway) | latest | -| [ArXiv MCP Server](./mcp-servers/arxiv-mcp-server) | latest | -| [Basic Memory](./mcp-servers/basic-memory) | latest | -| [ClickHouse](./mcp-servers/clickhouse) | latest | -| [Docker](./mcp-servers/docker) | latest | -| [Dockerhub](./mcp-servers/dockerhub) | latest | -| [E2B](./mcp-servers/e2b) | latest | -| [ElevenLabs](./mcp-servers/elevenlabs) | latest | -| [Fetch](./mcp-servers/fetch) | latest | -| [Firecrawl](./mcp-servers/firecrawl) | latest | -| [Filesystem](./mcp-servers/filesystem) | latest | -| [Grafana](./mcp-servers/grafana) | latest | -| [Markdownify](./mcp-servers/markdownify) | latest | -| [Markitdown](./mcp-servers/markitdown) | latest | -| [Memory](./mcp-servers/memory) | latest | -| [MongoDB](./mcp-servers/mongodb) | latest | -| [Neo4j Cypher](./mcp-servers/neo4j-cypher) | latest | -| [Neo4j Memory](./mcp-servers/neo4j-memory) | latest | -| [Notion](./mcp-servers/notion) | latest | -| [OpenAPI Schema](./mcp-servers/openapi-schema) | latest | -| [OpenAPI](./mcp-servers/openapi) | latest | -| [OpenWeather](./mcp-servers/openweather) | latest | -| [Paper Search](./mcp-servers/paper-search) | latest | -| [Playwright](./mcp-servers/playwright) | latest | -| [Redis MCP](./mcp-servers/redis-mcp) | latest | -| [Rust Filesystem](./mcp-servers/rust-mcp-filesystem) | latest | -| [Sequential Thinking](./mcp-servers/sequentialthinking) | latest | -| [SQLite](./mcp-servers/sqlite) | latest | -| [Tavily](./mcp-servers/tavily) | latest | -| [Text to GraphQL](./mcp-servers/text-to-graphql) | latest | -| [Time](./mcp-servers/time) | latest | -| [Wolfram Alpha](./mcp-servers/wolfram-alpha) | latest | -| [YouTube Transcript](./mcp-servers/youtube-transcript) | latest | - -## Guidelines - -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](./LICENSE). +# 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 | +| ------------------------------------------------------------- | ---------------------------- | +| [Apache APISIX](./src/apisix) | 3.13.0 | +| [Apache Cassandra](./src/cassandra) | 5.0.2 | +| [Apache Flink](./src/flink) | 1.20.0 | +| [Apache HBase](./src/hbase) | 2.6 | +| [Apache HTTP Server](./src/apache) | 2.4.62 | +| [Apache Kafka](./src/kafka) | 7.8.0 | +| [Apache Pulsar](./src/pulsar) | 4.0.7 | +| [Apache RocketMQ](./src/rocketmq) | 5.3.1 | +| [Bifrost Gateway](./src/bifrost-gateway) | 1.3.48 | +| [Bolt.diy](./src/bolt-diy) | latest | +| [Budibase](./src/budibase) | 3.23.0 | +| [Bytebot](./src/bytebot) | edge | +| [Clash](./src/clash) | 1.18.0 | +| [ClickHouse](./src/clickhouse) | 24.11.1 | +| [Conductor](./src/conductor) | latest | +| [Dify](./src/dify) | 0.18.2 | +| [DNSMasq](./src/dnsmasq) | 2.91 | +| [Dockge](./src/dockge) | 1 | +| [Docker Registry](./src/docker-registry) | 3.0.0 | +| [DuckDB](./src/duckdb) | v1.1.3 | +| [Easy Dataset](./src/easy-dataset) | 1.5.1 | +| [Elasticsearch](./src/elasticsearch) | 8.16.1 | +| [etcd](./src/etcd) | 3.6.0 | +| [Firecrawl](./src/firecrawl) | latest | +| [frpc](./src/frpc) | 0.64.0 | +| [frps](./src/frps) | 0.64.0 | +| [Gitea Runner](./src/gitea-runner) | 0.2.13 | +| [Gitea](./src/gitea) | 1.24.6 | +| [GitLab Runner](./src/gitlab-runner) | 17.10.1 | +| [GitLab](./src/gitlab) | 17.10.4-ce.0 | +| [GPUStack](./src/gpustack) | v0.5.3 | +| [Grafana](./src/grafana) | 12.1.1 | +| [Halo](./src/halo) | 2.21.9 | +| [Harbor](./src/harbor) | v2.12.0 | +| [HashiCorp Consul](./src/consul) | 1.20.3 | +| [IOPaint](./builds/io-paint) | latest | +| [Jenkins](./src/jenkins) | 2.486-lts | +| [JODConverter](./src/jodconverter) | latest | +| [Kestra](./src/kestra) | latest-full | +| [Kibana](./src/kibana) | 8.16.1 | +| [Kodbox](./src/kodbox) | 1.62 | +| [Kong](./src/kong) | 3.8.0 | +| [Langflow](./apps/langflow) | latest | +| [Langfuse](./apps/langfuse) | 3.115.0 | +| [LibreOffice](./src/libreoffice) | latest | +| [libSQL Server](./src/libsql) | latest | +| [LiteLLM](./src/litellm) | main-stable | +| [Logstash](./src/logstash) | 8.16.1 | +| [MariaDB Galera Cluster](./src/mariadb-galera) | 11.7.2 | +| [Milvus Standalone Embed](./src/milvus-standalone-embed) | 2.6.2 | +| [Milvus Standalone](./src/milvus-standalone) | 2.6.2 | +| [Minecraft Bedrock Server](./src/minecraft-bedrock-server) | latest | +| [MinerU SGLang](./src/mineru-sglang) | 2.2.2 | +| [MinerU vLLM](./builds/mineru-vllm) | 2.6.4 | +| [MinIO](./src/minio) | RELEASE.2025-09-07T16-13-09Z | +| [MLflow](./src/mlflow) | v2.20.2 | +| [MongoDB ReplicaSet Single](./src/mongodb-replicaset-single) | 8.0.13 | +| [MongoDB ReplicaSet](./src/mongodb-replicaset) | 8.0.13 | +| [MongoDB Standalone](./src/mongodb-standalone) | 8.0.13 | +| [MySQL](./src/mysql) | 9.4.0 | +| [n8n](./src/n8n) | 1.114.0 | +| [Nacos](./src/nacos) | v3.1.0 | +| [NebulaGraph](./src/nebulagraph) | v3.8.0 | +| [NexaSDK](./src/nexa-sdk) | v0.2.62 | +| [Neo4j](./src/neo4j) | 5.27.4 | +| [Netdata](./src/netdata) | latest | +| [Nginx](./src/nginx) | 1.29.1 | +| [Node Exporter](./src/node-exporter) | v1.8.2 | +| [OceanBase](./src/oceanbase) | 4.3.3 | +| [Odoo](./src/odoo) | 19.0 | +| [Ollama](./src/ollama) | 0.12.0 | +| [Open WebUI](./src/open-webui) | main | +| [Phoenix (Arize)](./src/phoenix) | 12.19.0 | +| [Pingora Proxy Manager](./src/pingora-proxy-manager) | v1.0.3 | +| [Open WebUI Rust](./src/open-webui-rust) | latest | +| [OpenCoze](./src/opencoze) | See Docs | +| [OpenCut](./src/opencut) | latest | +| [OpenList](./src/openlist) | latest | +| [OpenSearch](./src/opensearch) | 2.19.0 | +| [PocketBase](./src/pocketbase) | 0.30.0 | +| [Portainer](./src/portainer) | 2.27.3-alpine | +| [Portkey AI Gateway](./src/portkey-gateway) | latest | +| [PostgreSQL](./src/postgres) | 17.6 | +| [Prometheus](./src/prometheus) | 3.5.0 | +| [PyTorch](./src/pytorch) | 2.6.0 | +| [Qdrant](./src/qdrant) | 1.15.4 | +| [RabbitMQ](./src/rabbitmq) | 4.1.4 | +| [Ray](./src/ray) | 2.42.1 | +| [Redpanda](./src/redpanda) | v24.3.1 | +| [Redis Cluster](./src/redis-cluster) | 8.2.1 | +| [Redis](./src/redis) | 8.2.1 | +| [Renovate](./src/renovate) | 42.52.5-full | +| [Restate Cluster](./src/restate-cluster) | 1.5.3 | +| [Restate](./src/restate) | 1.5.3 | +| [SearXNG](./src/searxng) | 2025.1.20-1ce14ef99 | +| [Sim](./apps/sim) | latest | +| [Stable Diffusion WebUI](./src/stable-diffusion-webui-docker) | latest | +| [Stirling-PDF](./src/stirling-pdf) | latest | +| [Temporal](./src/temporal) | 1.24.2 | +| [TiDB](./src/tidb) | v8.5.0 | +| [TiKV](./src/tikv) | v8.5.0 | +| [Trigger.dev](./src/trigger-dev) | v4.2.0 | +| [TrailBase](./src/trailbase) | 0.22.4 | +| [Valkey Cluster](./src/valkey-cluster) | 8.0 | +| [Valkey](./src/valkey) | 8.0 | +| [Verdaccio](./src/verdaccio) | 6.1.2 | +| [vLLM](./src/vllm) | v0.8.0 | +| [Windmill](./src/windmill) | main | +| [ZooKeeper](./src/zookeeper) | 3.9.3 | + +## MCP Servers + +| Server | Version | +| ------------------------------------------------------- | ------- | +| [API Gateway](./mcp-servers/api-gateway) | latest | +| [ArXiv MCP Server](./mcp-servers/arxiv-mcp-server) | latest | +| [Basic Memory](./mcp-servers/basic-memory) | latest | +| [ClickHouse](./mcp-servers/clickhouse) | latest | +| [Docker](./mcp-servers/docker) | latest | +| [Dockerhub](./mcp-servers/dockerhub) | latest | +| [E2B](./mcp-servers/e2b) | latest | +| [ElevenLabs](./mcp-servers/elevenlabs) | latest | +| [Fetch](./mcp-servers/fetch) | latest | +| [Firecrawl](./mcp-servers/firecrawl) | latest | +| [Filesystem](./mcp-servers/filesystem) | latest | +| [Grafana](./mcp-servers/grafana) | latest | +| [Markdownify](./mcp-servers/markdownify) | latest | +| [Markitdown](./mcp-servers/markitdown) | latest | +| [Memory](./mcp-servers/memory) | latest | +| [MongoDB](./mcp-servers/mongodb) | latest | +| [Neo4j Cypher](./mcp-servers/neo4j-cypher) | latest | +| [Neo4j Memory](./mcp-servers/neo4j-memory) | latest | +| [Notion](./mcp-servers/notion) | latest | +| [OpenAPI Schema](./mcp-servers/openapi-schema) | latest | +| [OpenAPI](./mcp-servers/openapi) | latest | +| [OpenWeather](./mcp-servers/openweather) | latest | +| [Paper Search](./mcp-servers/paper-search) | latest | +| [Playwright](./mcp-servers/playwright) | latest | +| [Redis MCP](./mcp-servers/redis-mcp) | latest | +| [Rust Filesystem](./mcp-servers/rust-mcp-filesystem) | latest | +| [Sequential Thinking](./mcp-servers/sequentialthinking) | latest | +| [SQLite](./mcp-servers/sqlite) | latest | +| [Tavily](./mcp-servers/tavily) | latest | +| [Text to GraphQL](./mcp-servers/text-to-graphql) | latest | +| [Time](./mcp-servers/time) | latest | +| [Wolfram Alpha](./mcp-servers/wolfram-alpha) | latest | +| [YouTube Transcript](./mcp-servers/youtube-transcript) | latest | + +## Guidelines + +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](./LICENSE). diff --git a/README.zh.md b/README.zh.md index 4dccdcf..126855b 100644 --- a/README.zh.md +++ b/README.zh.md @@ -1,204 +1,205 @@ -# Compose Anything - -Compose Anything 通过提供一组高质量的 Docker Compose 配置文件，帮助用户快速部署各种服务。这些配置约束了资源使用，可快速迁移到 K8S 等系统，并且易于理解和修改。 - -## 已经支持的服务 - -| 服务 | 版本 | -| ------------------------------------------------------------- | ---------------------------- | -| [Apache APISIX](./src/apisix) | 3.13.0 | -| [Apache Cassandra](./src/cassandra) | 5.0.2 | -| [Apache Flink](./src/flink) | 1.20.0 | -| [Apache HBase](./src/hbase) | 2.6 | -| [Apache HTTP Server](./src/apache) | 2.4.62 | -| [Apache Kafka](./src/kafka) | 7.8.0 | -| [Apache Pulsar](./src/pulsar) | 4.0.7 | -| [Apache RocketMQ](./src/rocketmq) | 5.3.1 | -| [Bifrost Gateway](./src/bifrost-gateway) | 1.3.48 | -| [Bolt.diy](./src/bolt-diy) | latest | -| [Budibase](./src/budibase) | 3.23.0 | -| [Bytebot](./src/bytebot) | edge | -| [Clash](./src/clash) | 1.18.0 | -| [ClickHouse](./src/clickhouse) | 24.11.1 | -| [Conductor](./src/conductor) | latest | -| [Dify](./src/dify) | 0.18.2 | -| [DNSMasq](./src/dnsmasq) | 2.91 | -| [Dockge](./src/dockge) | 1 | -| [Docker Registry](./src/docker-registry) | 3.0.0 | -| [DuckDB](./src/duckdb) | v1.1.3 | -| [Easy Dataset](./src/easy-dataset) | 1.5.1 | -| [Elasticsearch](./src/elasticsearch) | 8.16.1 | -| [etcd](./src/etcd) | 3.6.0 | -| [Firecrawl](./src/firecrawl) | latest | -| [frpc](./src/frpc) | 0.64.0 | -| [frps](./src/frps) | 0.64.0 | -| [Gitea Runner](./src/gitea-runner) | 0.2.13 | -| [Gitea](./src/gitea) | 1.24.6 | -| [GitLab Runner](./src/gitlab-runner) | 17.10.1 | -| [GitLab](./src/gitlab) | 17.10.4-ce.0 | -| [GPUStack](./src/gpustack) | v0.5.3 | -| [Grafana](./src/grafana) | 12.1.1 | -| [Halo](./src/halo) | 2.21.9 | -| [Harbor](./src/harbor) | v2.12.0 | -| [HashiCorp Consul](./src/consul) | 1.20.3 | -| [IOPaint](./builds/io-paint) | latest | -| [Jenkins](./src/jenkins) | 2.486-lts | -| [JODConverter](./src/jodconverter) | latest | -| [Kestra](./src/kestra) | latest-full | -| [Kibana](./src/kibana) | 8.16.1 | -| [Kodbox](./src/kodbox) | 1.62 | -| [Kong](./src/kong) | 3.8.0 | -| [Langflow](./apps/langflow) | latest | -| [Langfuse](./apps/langfuse) | 3.115.0 | -| [LibreOffice](./src/libreoffice) | latest | -| [LiteLLM](./src/litellm) | main-stable | -| [Logstash](./src/logstash) | 8.16.1 | -| [MariaDB Galera 集群](./src/mariadb-galera) | 11.7.2 | -| [Milvus Standalone Embed](./src/milvus-standalone-embed) | 2.6.2 | -| [Milvus Standalone](./src/milvus-standalone) | 2.6.2 | -| [Minecraft Bedrock Server](./src/minecraft-bedrock-server) | latest | -| [MinerU SGLang](./src/mineru-sglang) | 2.2.2 | -| [MinerU vLLM](./builds/mineru-vllm) | 2.6.4 | -| [MinIO](./src/minio) | RELEASE.2025-09-07T16-13-09Z | -| [MLflow](./src/mlflow) | v2.20.2 | -| [MongoDB ReplicaSet Single](./src/mongodb-replicaset-single) | 8.0.13 | -| [MongoDB ReplicaSet](./src/mongodb-replicaset) | 8.0.13 | -| [MongoDB Standalone](./src/mongodb-standalone) | 8.0.13 | -| [MySQL](./src/mysql) | 9.4.0 | -| [n8n](./src/n8n) | 1.114.0 | -| [Nacos](./src/nacos) | v3.1.0 | -| [NebulaGraph](./src/nebulagraph) | v3.8.0 | -| [NexaSDK](./src/nexa-sdk) | v0.2.62 | -| [Neo4j](./src/neo4j) | 5.27.4 | -| [Netdata](./src/netdata) | latest | -| [Nginx](./src/nginx) | 1.29.1 | -| [Node Exporter](./src/node-exporter) | v1.8.2 | -| [OceanBase](./src/oceanbase) | 4.3.3 | -| [Odoo](./src/odoo) | 19.0 | -| [Ollama](./src/ollama) | 0.12.0 | -| [Open WebUI](./src/open-webui) | main | -| [Phoenix (Arize)](./src/phoenix) | 12.19.0 | -| [Pingora Proxy Manager](./src/pingora-proxy-manager) | v1.0.3 | -| [Open WebUI Rust](./src/open-webui-rust) | latest | -| [OpenCoze](./src/opencoze) | See Docs | -| [OpenCut](./src/opencut) | latest | -| [OpenList](./src/openlist) | latest | -| [OpenSearch](./src/opensearch) | 2.19.0 | -| [PocketBase](./src/pocketbase) | 0.30.0 | -| [Portainer](./src/portainer) | 2.27.3-alpine | -| [Portkey AI Gateway](./src/portkey-gateway) | latest | -| [PostgreSQL](./src/postgres) | 17.6 | -| [Prometheus](./src/prometheus) | 3.5.0 | -| [PyTorch](./src/pytorch) | 2.6.0 | -| [Qdrant](./src/qdrant) | 1.15.4 | -| [RabbitMQ](./src/rabbitmq) | 4.1.4 | -| [Ray](./src/ray) | 2.42.1 | -| [Redpanda](./src/redpanda) | v24.3.1 | -| [Redis Cluster](./src/redis-cluster) | 8.2.1 | -| [Redis](./src/redis) | 8.2.1 | -| [Renovate](./src/renovate) | 42.52.5-full | -| [Restate Cluster](./src/restate-cluster) | 1.5.3 | -| [Restate](./src/restate) | 1.5.3 | -| [SearXNG](./src/searxng) | 2025.1.20-1ce14ef99 | -| [Sim](./apps/sim) | latest | -| [Stable Diffusion WebUI](./src/stable-diffusion-webui-docker) | latest | -| [Stirling-PDF](./src/stirling-pdf) | latest | -| [Temporal](./src/temporal) | 1.24.2 | -| [TiDB](./src/tidb) | v8.5.0 | -| [TiKV](./src/tikv) | v8.5.0 | -| [Trigger.dev](./src/trigger-dev) | v4.2.0 | -| [TrailBase](./src/trailbase) | 0.22.4 | -| [Valkey Cluster](./src/valkey-cluster) | 8.0 | -| [Valkey](./src/valkey) | 8.0 | -| [Verdaccio](./src/verdaccio) | 6.1.2 | -| [vLLM](./src/vllm) | v0.8.0 | -| [Windmill](./src/windmill) | main | -| [ZooKeeper](./src/zookeeper) | 3.9.3 | - -## MCP 服务器 - -| 服务 | 版本 | -| ------------------------------------------------------- | ------ | -| [API Gateway](./mcp-servers/api-gateway) | latest | -| [ArXiv MCP Server](./mcp-servers/arxiv-mcp-server) | latest | -| [Basic Memory](./mcp-servers/basic-memory) | latest | -| [ClickHouse](./mcp-servers/clickhouse) | latest | -| [Docker](./mcp-servers/docker) | latest | -| [Dockerhub](./mcp-servers/dockerhub) | latest | -| [E2B](./mcp-servers/e2b) | latest | -| [ElevenLabs](./mcp-servers/elevenlabs) | latest | -| [Fetch](./mcp-servers/fetch) | latest | -| [Firecrawl](./mcp-servers/firecrawl) | latest | -| [Filesystem](./mcp-servers/filesystem) | latest | -| [Grafana](./mcp-servers/grafana) | latest | -| [Markdownify](./mcp-servers/markdownify) | latest | -| [Markitdown](./mcp-servers/markitdown) | latest | -| [Memory](./mcp-servers/memory) | latest | -| [MongoDB](./mcp-servers/mongodb) | latest | -| [Neo4j Cypher](./mcp-servers/neo4j-cypher) | latest | -| [Neo4j Memory](./mcp-servers/neo4j-memory) | latest | -| [Notion](./mcp-servers/notion) | latest | -| [OpenAPI Schema](./mcp-servers/openapi-schema) | latest | -| [OpenAPI](./mcp-servers/openapi) | latest | -| [OpenWeather](./mcp-servers/openweather) | latest | -| [Paper Search](./mcp-servers/paper-search) | latest | -| [Playwright](./mcp-servers/playwright) | latest | -| [Redis MCP](./mcp-servers/redis-mcp) | latest | -| [Rust Filesystem](./mcp-servers/rust-mcp-filesystem) | latest | -| [Sequential Thinking](./mcp-servers/sequentialthinking) | latest | -| [SQLite](./mcp-servers/sqlite) | latest | -| [Tavily](./mcp-servers/tavily) | latest | -| [Text to GraphQL](./mcp-servers/text-to-graphql) | latest | -| [Time](./mcp-servers/time) | latest | -| [Wolfram Alpha](./mcp-servers/wolfram-alpha) | latest | -| [YouTube Transcript](./mcp-servers/youtube-transcript) | latest | - -## 规范 - -1. 开箱即用 - - 配置应该是开箱即用的，无需额外步骤即可启动（最多提供 `.env` 文件）。 -2. 命令简单 - - 每个项目提供单一的 `docker-compose.yaml` 文件； - - 命令复杂度不应超过 `docker compose up -d`；若需要额外流程，请提供 `Makefile`； - - 若服务需要初始化，优先使用 `healthcheck` 与 `depends_on` 的 `condition: service_healthy` 组织启动顺序。 -3. 版本稳定 - - 固定到“最新稳定版”而非 `latest`； - - 通过环境变量暴露镜像版本（如 `FOO_VERSION`）。 -4. 配置约定 - - 尽量通过环境变量配置，而非复杂的命令行参数； - - 敏感信息通过环境变量或挂载文件传递，不要硬编码； - - 提供合理默认值，实现零配置可启动； - - 必须提供带注释的 `.env.example`； - - 环境变量命名建议：全大写、下划线分隔，按服务加前缀（如 `POSTGRES_*`），端口覆写统一用 `*_PORT_OVERRIDE`。 -5. Profiles 规范 - - 对“可选组件/依赖”使用 Profiles； - - 推荐命名：`gpu`（GPU 加速）、`metrics`（可观测性/导出器）、`dev`（开发特性）。 -6. 跨平台与架构 - - 在镜像支持前提下，确保 Debian 12+/Ubuntu 22.04+、Windows 10+、macOS 12+ 可用； - - 支持 x86-64 与 ARM64 架构尽可能一致； - - 避免依赖仅在 Linux 主机存在的主机路径（例如 `/etc/localtime`、`/etc/timezone`），统一使用 `TZ` 环境变量传递时区。 -7. 卷与挂载 - - 配置文件优先使用相对路径，增强跨平台兼容； - - 数据目录优先使用“命名卷”，避免主机路径权限/兼容性问题； - - 如需主机路径，建议提供顶层目录变量（如 `DATA_DIR`）。 -8. 资源与日志 - - 必须限制 CPU/内存，防止资源打爆； - - GPU 服务默认单卡：可使用 `deploy.resources.reservations.devices`（Compose 支持为 device_requests 映射）或 `gpus`； - - 限制日志大小（`json-file`：`max-size`/`max-file`）。 -9. 健康检查 - - 每个服务应提供 `healthcheck`，包括合适的 `interval`、`timeout`、`retries` 与 `start_period`； - - 依赖链通过 `depends_on.condition: service_healthy` 组织。 -10. 安全基线（能用则用） - - 以非 root 运行（提供 `PUID`/`PGID` 或直接 `user: "1000:1000"`）； - - 只读根文件系统（`read_only: true`），必要目录使用 `tmpfs`/可写挂载； - - 最小权限：`cap_drop: ["ALL"]`，按需再 `cap_add`； - - 避免使用 `container_name`（影响可扩缩与复用网络别名）； - - 如需暴露 Docker 套接字等高危挂载，必须在文档中明确“风险与替代方案”。 -11. 文档与可发现性 - - 提供清晰文档与示例（含初始化与管理员账号说明、必要的安全/许可说明）； - - 提供对 LLM 友好的结构化文档； - - 在 README 中标注主要环境变量与默认端口，并链接到 `README.md` / `README.zh.md`。 - -## 开源协议 - -[MIT License](./LICENSE). +# Compose Anything + +Compose Anything 通过提供一组高质量的 Docker Compose 配置文件，帮助用户快速部署各种服务。这些配置约束了资源使用，可快速迁移到 K8S 等系统，并且易于理解和修改。 + +## 已经支持的服务 + +| 服务 | 版本 | +| ------------------------------------------------------------- | ---------------------------- | +| [Apache APISIX](./src/apisix) | 3.13.0 | +| [Apache Cassandra](./src/cassandra) | 5.0.2 | +| [Apache Flink](./src/flink) | 1.20.0 | +| [Apache HBase](./src/hbase) | 2.6 | +| [Apache HTTP Server](./src/apache) | 2.4.62 | +| [Apache Kafka](./src/kafka) | 7.8.0 | +| [Apache Pulsar](./src/pulsar) | 4.0.7 | +| [Apache RocketMQ](./src/rocketmq) | 5.3.1 | +| [Bifrost Gateway](./src/bifrost-gateway) | 1.3.48 | +| [Bolt.diy](./src/bolt-diy) | latest | +| [Budibase](./src/budibase) | 3.23.0 | +| [Bytebot](./src/bytebot) | edge | +| [Clash](./src/clash) | 1.18.0 | +| [ClickHouse](./src/clickhouse) | 24.11.1 | +| [Conductor](./src/conductor) | latest | +| [Dify](./src/dify) | 0.18.2 | +| [DNSMasq](./src/dnsmasq) | 2.91 | +| [Dockge](./src/dockge) | 1 | +| [Docker Registry](./src/docker-registry) | 3.0.0 | +| [DuckDB](./src/duckdb) | v1.1.3 | +| [Easy Dataset](./src/easy-dataset) | 1.5.1 | +| [Elasticsearch](./src/elasticsearch) | 8.16.1 | +| [etcd](./src/etcd) | 3.6.0 | +| [Firecrawl](./src/firecrawl) | latest | +| [frpc](./src/frpc) | 0.64.0 | +| [frps](./src/frps) | 0.64.0 | +| [Gitea Runner](./src/gitea-runner) | 0.2.13 | +| [Gitea](./src/gitea) | 1.24.6 | +| [GitLab Runner](./src/gitlab-runner) | 17.10.1 | +| [GitLab](./src/gitlab) | 17.10.4-ce.0 | +| [GPUStack](./src/gpustack) | v0.5.3 | +| [Grafana](./src/grafana) | 12.1.1 | +| [Halo](./src/halo) | 2.21.9 | +| [Harbor](./src/harbor) | v2.12.0 | +| [HashiCorp Consul](./src/consul) | 1.20.3 | +| [IOPaint](./builds/io-paint) | latest | +| [Jenkins](./src/jenkins) | 2.486-lts | +| [JODConverter](./src/jodconverter) | latest | +| [Kestra](./src/kestra) | latest-full | +| [Kibana](./src/kibana) | 8.16.1 | +| [Kodbox](./src/kodbox) | 1.62 | +| [Kong](./src/kong) | 3.8.0 | +| [Langflow](./apps/langflow) | latest | +| [Langfuse](./apps/langfuse) | 3.115.0 | +| [LibreOffice](./src/libreoffice) | latest | +| [libSQL Server](./src/libsql) | latest | +| [LiteLLM](./src/litellm) | main-stable | +| [Logstash](./src/logstash) | 8.16.1 | +| [MariaDB Galera 集群](./src/mariadb-galera) | 11.7.2 | +| [Milvus Standalone Embed](./src/milvus-standalone-embed) | 2.6.2 | +| [Milvus Standalone](./src/milvus-standalone) | 2.6.2 | +| [Minecraft Bedrock Server](./src/minecraft-bedrock-server) | latest | +| [MinerU SGLang](./src/mineru-sglang) | 2.2.2 | +| [MinerU vLLM](./builds/mineru-vllm) | 2.6.4 | +| [MinIO](./src/minio) | RELEASE.2025-09-07T16-13-09Z | +| [MLflow](./src/mlflow) | v2.20.2 | +| [MongoDB ReplicaSet Single](./src/mongodb-replicaset-single) | 8.0.13 | +| [MongoDB ReplicaSet](./src/mongodb-replicaset) | 8.0.13 | +| [MongoDB Standalone](./src/mongodb-standalone) | 8.0.13 | +| [MySQL](./src/mysql) | 9.4.0 | +| [n8n](./src/n8n) | 1.114.0 | +| [Nacos](./src/nacos) | v3.1.0 | +| [NebulaGraph](./src/nebulagraph) | v3.8.0 | +| [NexaSDK](./src/nexa-sdk) | v0.2.62 | +| [Neo4j](./src/neo4j) | 5.27.4 | +| [Netdata](./src/netdata) | latest | +| [Nginx](./src/nginx) | 1.29.1 | +| [Node Exporter](./src/node-exporter) | v1.8.2 | +| [OceanBase](./src/oceanbase) | 4.3.3 | +| [Odoo](./src/odoo) | 19.0 | +| [Ollama](./src/ollama) | 0.12.0 | +| [Open WebUI](./src/open-webui) | main | +| [Phoenix (Arize)](./src/phoenix) | 12.19.0 | +| [Pingora Proxy Manager](./src/pingora-proxy-manager) | v1.0.3 | +| [Open WebUI Rust](./src/open-webui-rust) | latest | +| [OpenCoze](./src/opencoze) | See Docs | +| [OpenCut](./src/opencut) | latest | +| [OpenList](./src/openlist) | latest | +| [OpenSearch](./src/opensearch) | 2.19.0 | +| [PocketBase](./src/pocketbase) | 0.30.0 | +| [Portainer](./src/portainer) | 2.27.3-alpine | +| [Portkey AI Gateway](./src/portkey-gateway) | latest | +| [PostgreSQL](./src/postgres) | 17.6 | +| [Prometheus](./src/prometheus) | 3.5.0 | +| [PyTorch](./src/pytorch) | 2.6.0 | +| [Qdrant](./src/qdrant) | 1.15.4 | +| [RabbitMQ](./src/rabbitmq) | 4.1.4 | +| [Ray](./src/ray) | 2.42.1 | +| [Redpanda](./src/redpanda) | v24.3.1 | +| [Redis Cluster](./src/redis-cluster) | 8.2.1 | +| [Redis](./src/redis) | 8.2.1 | +| [Renovate](./src/renovate) | 42.52.5-full | +| [Restate Cluster](./src/restate-cluster) | 1.5.3 | +| [Restate](./src/restate) | 1.5.3 | +| [SearXNG](./src/searxng) | 2025.1.20-1ce14ef99 | +| [Sim](./apps/sim) | latest | +| [Stable Diffusion WebUI](./src/stable-diffusion-webui-docker) | latest | +| [Stirling-PDF](./src/stirling-pdf) | latest | +| [Temporal](./src/temporal) | 1.24.2 | +| [TiDB](./src/tidb) | v8.5.0 | +| [TiKV](./src/tikv) | v8.5.0 | +| [Trigger.dev](./src/trigger-dev) | v4.2.0 | +| [TrailBase](./src/trailbase) | 0.22.4 | +| [Valkey Cluster](./src/valkey-cluster) | 8.0 | +| [Valkey](./src/valkey) | 8.0 | +| [Verdaccio](./src/verdaccio) | 6.1.2 | +| [vLLM](./src/vllm) | v0.8.0 | +| [Windmill](./src/windmill) | main | +| [ZooKeeper](./src/zookeeper) | 3.9.3 | + +## MCP 服务器 + +| 服务 | 版本 | +| ------------------------------------------------------- | ------ | +| [API Gateway](./mcp-servers/api-gateway) | latest | +| [ArXiv MCP Server](./mcp-servers/arxiv-mcp-server) | latest | +| [Basic Memory](./mcp-servers/basic-memory) | latest | +| [ClickHouse](./mcp-servers/clickhouse) | latest | +| [Docker](./mcp-servers/docker) | latest | +| [Dockerhub](./mcp-servers/dockerhub) | latest | +| [E2B](./mcp-servers/e2b) | latest | +| [ElevenLabs](./mcp-servers/elevenlabs) | latest | +| [Fetch](./mcp-servers/fetch) | latest | +| [Firecrawl](./mcp-servers/firecrawl) | latest | +| [Filesystem](./mcp-servers/filesystem) | latest | +| [Grafana](./mcp-servers/grafana) | latest | +| [Markdownify](./mcp-servers/markdownify) | latest | +| [Markitdown](./mcp-servers/markitdown) | latest | +| [Memory](./mcp-servers/memory) | latest | +| [MongoDB](./mcp-servers/mongodb) | latest | +| [Neo4j Cypher](./mcp-servers/neo4j-cypher) | latest | +| [Neo4j Memory](./mcp-servers/neo4j-memory) | latest | +| [Notion](./mcp-servers/notion) | latest | +| [OpenAPI Schema](./mcp-servers/openapi-schema) | latest | +| [OpenAPI](./mcp-servers/openapi) | latest | +| [OpenWeather](./mcp-servers/openweather) | latest | +| [Paper Search](./mcp-servers/paper-search) | latest | +| [Playwright](./mcp-servers/playwright) | latest | +| [Redis MCP](./mcp-servers/redis-mcp) | latest | +| [Rust Filesystem](./mcp-servers/rust-mcp-filesystem) | latest | +| [Sequential Thinking](./mcp-servers/sequentialthinking) | latest | +| [SQLite](./mcp-servers/sqlite) | latest | +| [Tavily](./mcp-servers/tavily) | latest | +| [Text to GraphQL](./mcp-servers/text-to-graphql) | latest | +| [Time](./mcp-servers/time) | latest | +| [Wolfram Alpha](./mcp-servers/wolfram-alpha) | latest | +| [YouTube Transcript](./mcp-servers/youtube-transcript) | latest | + +## 规范 + +1. 开箱即用 + - 配置应该是开箱即用的，无需额外步骤即可启动（最多提供 `.env` 文件）。 +2. 命令简单 + - 每个项目提供单一的 `docker-compose.yaml` 文件； + - 命令复杂度不应超过 `docker compose up -d`；若需要额外流程，请提供 `Makefile`； + - 若服务需要初始化，优先使用 `healthcheck` 与 `depends_on` 的 `condition: service_healthy` 组织启动顺序。 +3. 版本稳定 + - 固定到“最新稳定版”而非 `latest`； + - 通过环境变量暴露镜像版本（如 `FOO_VERSION`）。 +4. 配置约定 + - 尽量通过环境变量配置，而非复杂的命令行参数； + - 敏感信息通过环境变量或挂载文件传递，不要硬编码； + - 提供合理默认值，实现零配置可启动； + - 必须提供带注释的 `.env.example`； + - 环境变量命名建议：全大写、下划线分隔，按服务加前缀（如 `POSTGRES_*`），端口覆写统一用 `*_PORT_OVERRIDE`。 +5. Profiles 规范 + - 对“可选组件/依赖”使用 Profiles； + - 推荐命名：`gpu`（GPU 加速）、`metrics`（可观测性/导出器）、`dev`（开发特性）。 +6. 跨平台与架构 + - 在镜像支持前提下，确保 Debian 12+/Ubuntu 22.04+、Windows 10+、macOS 12+ 可用； + - 支持 x86-64 与 ARM64 架构尽可能一致； + - 避免依赖仅在 Linux 主机存在的主机路径（例如 `/etc/localtime`、`/etc/timezone`），统一使用 `TZ` 环境变量传递时区。 +7. 卷与挂载 + - 配置文件优先使用相对路径，增强跨平台兼容； + - 数据目录优先使用“命名卷”，避免主机路径权限/兼容性问题； + - 如需主机路径，建议提供顶层目录变量（如 `DATA_DIR`）。 +8. 资源与日志 + - 必须限制 CPU/内存，防止资源打爆； + - GPU 服务默认单卡：可使用 `deploy.resources.reservations.devices`（Compose 支持为 device_requests 映射）或 `gpus`； + - 限制日志大小（`json-file`：`max-size`/`max-file`）。 +9. 健康检查 + - 每个服务应提供 `healthcheck`，包括合适的 `interval`、`timeout`、`retries` 与 `start_period`； + - 依赖链通过 `depends_on.condition: service_healthy` 组织。 +10. 安全基线（能用则用） + - 以非 root 运行（提供 `PUID`/`PGID` 或直接 `user: "1000:1000"`）； + - 只读根文件系统（`read_only: true`），必要目录使用 `tmpfs`/可写挂载； + - 最小权限：`cap_drop: ["ALL"]`，按需再 `cap_add`； + - 避免使用 `container_name`（影响可扩缩与复用网络别名）； + - 如需暴露 Docker 套接字等高危挂载，必须在文档中明确“风险与替代方案”。 +11. 文档与可发现性 + - 提供清晰文档与示例（含初始化与管理员账号说明、必要的安全/许可说明）； + - 提供对 LLM 友好的结构化文档； + - 在 README 中标注主要环境变量与默认端口，并链接到 `README.md` / `README.zh.md`。 + +## 开源协议 + +[MIT License](./LICENSE). diff --git a/builds/debian-dind/.env.example b/builds/debian-dind/.env.example index 2d4e62b..f44b199 100644 --- a/builds/debian-dind/.env.example +++ b/builds/debian-dind/.env.example @@ -3,8 +3,8 @@ # Timezone (default: UTC) TZ=UTC -# Debian version (default: 13.2) -DEBIAN_VERSION=13.2 +# Debian version (default: 13.2-slim) +DEBIAN_VERSION=13.2-slim # Docker port override (default: 2375) DIND_PORT_OVERRIDE=2375 diff --git a/builds/debian-dind/Dockerfile b/builds/debian-dind/Dockerfile index 13fce9c..0d4615d 100644 --- a/builds/debian-dind/Dockerfile +++ b/builds/debian-dind/Dockerfile @@ -1,4 +1,4 @@ -ARG DEBIAN_VERSION=13.2 +ARG DEBIAN_VERSION=13.2-slim FROM debian:${DEBIAN_VERSION} # Install dependencies diff --git a/builds/debian-dind/README.md b/builds/debian-dind/README.md index e33c96e..c6b7361 100644 --- a/builds/debian-dind/README.md +++ b/builds/debian-dind/README.md @@ -4,7 +4,7 @@ A Docker-in-Docker (DinD) service based on Debian, allowing you to run Docker in ## Features -- Based on latest stable Debian (13.2) +- Based on latest stable Debian (13.2-slim) - Out-of-the-box Docker daemon - Optional NVIDIA Container Toolkit for GPU support - Resource limits configured @@ -36,14 +36,14 @@ A Docker-in-Docker (DinD) service based on Debian, allowing you to run Docker in Key environment variables (see `.env.example` for all options): -| Variable | Description | Default | -| ------------------------ | ----------------------------------- | ------- | -| `DEBIAN_VERSION` | Debian base image version | `13.2` | -| `DIND_PORT_OVERRIDE` | Host port for Docker daemon | `2375` | -| `INSTALL_NVIDIA_TOOLKIT` | Install NVIDIA toolkit during build | `false` | -| `TZ` | Timezone | `UTC` | -| `DIND_CPU_LIMIT` | CPU limit | `2.0` | -| `DIND_MEMORY_LIMIT` | Memory limit | `4G` | +| Variable | Description | Default | +| ------------------------ | ----------------------------------- | ----------- | +| `DEBIAN_VERSION` | Debian base image version | `13.2-slim` | +| `DIND_PORT_OVERRIDE` | Host port for Docker daemon | `2375` | +| `INSTALL_NVIDIA_TOOLKIT` | Install NVIDIA toolkit during build | `false` | +| `TZ` | Timezone | `UTC` | +| `DIND_CPU_LIMIT` | CPU limit | `2.0` | +| `DIND_MEMORY_LIMIT` | Memory limit | `4G` | ## GPU Support @@ -112,13 +112,13 @@ variables: When building the image manually: -- `DEBIAN_VERSION`: Debian base version (default: `13.2`) +- `DEBIAN_VERSION`: Debian base version (default: `13.2-slim`) - `INSTALL_NVIDIA_TOOLKIT`: Install NVIDIA toolkit (default: `false`) Example: ```bash -docker build --build-arg DEBIAN_VERSION=13.2 --build-arg INSTALL_NVIDIA_TOOLKIT=true -t debian-dind-gpu . +docker build --build-arg DEBIAN_VERSION=13.2-slim --build-arg INSTALL_NVIDIA_TOOLKIT=true -t debian-dind-gpu . ``` ## License diff --git a/builds/debian-dind/README.zh.md b/builds/debian-dind/README.zh.md index 9d5a064..93c0b80 100644 --- a/builds/debian-dind/README.zh.md +++ b/builds/debian-dind/README.zh.md @@ -4,7 +4,7 @@ ## 特性 -- 基于最新稳定版 Debian（13.2） +- 基于最新稳定版 Debian（13.2-slim） - 开箱即用的 Docker 守护进程 - 可选的 NVIDIA Container Toolkit，支持 GPU - 配置了资源限制 @@ -36,14 +36,14 @@ 主要环境变量（查看 `.env.example` 了解所有选项）： -| 变量 | 说明 | 默认值 | -| ------------------------ | ------------------------- | ------- | -| `DEBIAN_VERSION` | Debian 基础镜像版本 | `13.2` | -| `DIND_PORT_OVERRIDE` | Docker 守护进程的主机端口 | `2375` | -| `INSTALL_NVIDIA_TOOLKIT` | 构建时安装 NVIDIA 工具包 | `false` | -| `TZ` | 时区 | `UTC` | -| `DIND_CPU_LIMIT` | CPU 限制 | `2.0` | -| `DIND_MEMORY_LIMIT` | 内存限制 | `4G` | +| 变量 | 说明 | 默认值 | +| ------------------------ | ------------------------- | ----------- | +| `DEBIAN_VERSION` | Debian 基础镜像版本 | `13.2-slim` | +| `DIND_PORT_OVERRIDE` | Docker 守护进程的主机端口 | `2375` | +| `INSTALL_NVIDIA_TOOLKIT` | 构建时安装 NVIDIA 工具包 | `false` | +| `TZ` | 时区 | `UTC` | +| `DIND_CPU_LIMIT` | CPU 限制 | `2.0` | +| `DIND_MEMORY_LIMIT` | 内存限制 | `4G` | ## GPU 支持 @@ -112,13 +112,13 @@ variables: 手动构建镜像时： -- `DEBIAN_VERSION`：Debian 基础版本（默认：`13.2`） +- `DEBIAN_VERSION`：Debian 基础版本（默认：`13.2-slim`） - `INSTALL_NVIDIA_TOOLKIT`：安装 NVIDIA 工具包（默认：`false`） 示例： ```bash -docker build --build-arg DEBIAN_VERSION=13.2 --build-arg INSTALL_NVIDIA_TOOLKIT=true -t debian-dind-gpu . +docker build --build-arg DEBIAN_VERSION=13.2-slim --build-arg INSTALL_NVIDIA_TOOLKIT=true -t debian-dind-gpu . ``` ## 许可证 diff --git a/builds/debian-dind/docker-compose.yaml b/builds/debian-dind/docker-compose.yaml index 3695ca7..a0dc5e2 100644 --- a/builds/debian-dind/docker-compose.yaml +++ b/builds/debian-dind/docker-compose.yaml @@ -17,13 +17,13 @@ services: context: . dockerfile: Dockerfile args: - - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2} + - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2-slim} - INSTALL_NVIDIA_TOOLKIT=${INSTALL_NVIDIA_TOOLKIT:-false} privileged: true ports: - "${DIND_PORT_OVERRIDE:-2375}:2375" volumes: - - dind-data:/var/lib/docker + - dind_data:/var/lib/docker environment: - TZ=${TZ:-UTC} - DOCKER_TLS_CERTDIR=${DOCKER_TLS_CERTDIR:-} @@ -52,13 +52,13 @@ services: context: . dockerfile: Dockerfile args: - - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2} + - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2-slim} - INSTALL_NVIDIA_TOOLKIT=true privileged: true ports: - "${DIND_PORT_OVERRIDE:-2375}:2375" volumes: - - dind-gpu-data:/var/lib/docker + - dind_gpu_data:/var/lib/docker environment: - TZ=${TZ:-UTC} - DOCKER_TLS_CERTDIR=${DOCKER_TLS_CERTDIR:-} @@ -86,5 +86,5 @@ services: - gpu volumes: - dind-data: - dind-gpu-data: + dind_data: + dind_gpu_data: diff --git a/builds/debian-dind/dockerd-entrypoint.sh b/builds/debian-dind/dockerd-entrypoint.sh index e0fc9c1..426fb2b 100644 --- a/builds/debian-dind/dockerd-entrypoint.sh +++ b/builds/debian-dind/dockerd-entrypoint.sh @@ -5,46 +5,46 @@ set -e # https://github.com/docker-library/docker/blob/master/24/dind/dockerd-entrypoint.sh if [ -z "$DOCKER_HOST" ]; then - case "$1" in - dockerd*) - # If we're running dockerd, we need to make sure we have cgroups mounted - if [ ! -d /sys/fs/cgroup ]; then - mkdir -p /sys/fs/cgroup - fi - if ! mountpoint -q /sys/fs/cgroup; then - mount -t tmpfs -o uid=0,gid=0,mode=0755 cgroup /sys/fs/cgroup - fi + case "$1" in + dockerd*) + # If we're running dockerd, we need to make sure we have cgroups mounted + if [ ! -d /sys/fs/cgroup ]; then + mkdir -p /sys/fs/cgroup + fi + if ! mountpoint -q /sys/fs/cgroup; then + mount -t tmpfs -o uid=0,gid=0,mode=0755 cgroup /sys/fs/cgroup + fi - # Mount cgroup v2 if available and not mounted - if [ -e /sys/fs/cgroup/cgroup.controllers ] && ! mountpoint -q /sys/fs/cgroup; then - mount -t cgroup2 -o nsdelegate cgroup2 /sys/fs/cgroup - fi + # Mount cgroup v2 if available and not mounted + if [ -e /sys/fs/cgroup/cgroup.controllers ] && ! mountpoint -q /sys/fs/cgroup; then + mount -t cgroup2 -o nsdelegate cgroup2 /sys/fs/cgroup + fi - # If /sys/fs/cgroup is not a cgroup2 mount, we might need to mount cgroup v1 hierarchies - if ! mountpoint -q /sys/fs/cgroup || [ "$(stat -f -c %T /sys/fs/cgroup)" != "cgroup2fs" ]; then - if [ -d /sys/fs/cgroup/cgroup.controllers ]; then - # It is cgroup2 but maybe not mounted as such? - # Actually if it exists, it's likely v2. - : - else - # cgroup v1 - for subsystem in $(awk '/^[^#]/ { print $1 }' /proc/cgroups); do - mkdir -p "/sys/fs/cgroup/$subsystem" - if ! mountpoint -q "/sys/fs/cgroup/$subsystem"; then - mount -t cgroup -o "$subsystem" cgroup "/sys/fs/cgroup/$subsystem" - fi - done - fi - fi - ;; - esac + # If /sys/fs/cgroup is not a cgroup2 mount, we might need to mount cgroup v1 hierarchies + if ! mountpoint -q /sys/fs/cgroup || [ "$(stat -f -c %T /sys/fs/cgroup)" != "cgroup2fs" ]; then + if [ -d /sys/fs/cgroup/cgroup.controllers ]; then + # It is cgroup2 but maybe not mounted as such? + # Actually if it exists, it's likely v2. + : + else + # cgroup v1 + for subsystem in $(awk '/^[^#]/ { print $1 }' /proc/cgroups); do + mkdir -p "/sys/fs/cgroup/$subsystem" + if ! mountpoint -q "/sys/fs/cgroup/$subsystem"; then + mount -t cgroup -o "$subsystem" cgroup "/sys/fs/cgroup/$subsystem" + fi + done + fi + fi + ;; + esac fi if [ "$1" = 'dockerd' ] || [ "${1#-}" != "$1" ]; then - # if the first argument is "dockerd" or a flag (starts with -) - if [ "${1#-}" != "$1" ]; then - set -- dockerd "$@" - fi + # if the first argument is "dockerd" or a flag (starts with -) + if [ "${1#-}" != "$1" ]; then + set -- dockerd "$@" + fi # Explicitly use iptables-legacy if available, as it is often more stable for DinD if command -v update-alternatives >/dev/null; then diff --git a/builds/kata-inside-dind/.env.example b/builds/kata-inside-dind/.env.example index 0539ab8..0cbc6d2 100644 --- a/builds/kata-inside-dind/.env.example +++ b/builds/kata-inside-dind/.env.example @@ -2,7 +2,7 @@ # GLOBAL_REGISTRY=registry.example.com/ # Debian Version -DEBIAN_VERSION=13.2 +DEBIAN_VERSION=13.2-slim # Kata Containers Version KATA_VERSION=3.24.0 diff --git a/builds/kata-inside-dind/Dockerfile b/builds/kata-inside-dind/Dockerfile index f3de758..f55d054 100644 --- a/builds/kata-inside-dind/Dockerfile +++ b/builds/kata-inside-dind/Dockerfile @@ -1,4 +1,4 @@ -ARG DEBIAN_VERSION=13.2 +ARG DEBIAN_VERSION=13.2-slim FROM debian:${DEBIAN_VERSION} # Install dependencies @@ -57,7 +57,8 @@ RUN if [ "${ARCH}" = "amd64" ]; then ARCH="x86_64"; fi \ && curl -fsSL https://github.com/firecracker-microvm/firecracker/releases/download/v${FIRECRACKER_VERSION}/firecracker-v${FIRECRACKER_VERSION}-${ARCH}.tgz -o firecracker.tgz \ && tar -xzf firecracker.tgz \ && mv release-v${FIRECRACKER_VERSION}-${ARCH}/firecracker-v${FIRECRACKER_VERSION}-${ARCH} /usr/local/bin/firecracker \ - && chmod +x /usr/local/bin/firecracker \ + && mv release-v${FIRECRACKER_VERSION}-${ARCH}/jailer-v${FIRECRACKER_VERSION}-${ARCH} /usr/local/bin/jailer \ + && chmod +x /usr/local/bin/firecracker /usr/local/bin/jailer \ && rm -rf release-v${FIRECRACKER_VERSION}-${ARCH} firecracker.tgz # Set up dind diff --git a/builds/kata-inside-dind/README.md b/builds/kata-inside-dind/README.md index 6dadac2..4d87648 100644 --- a/builds/kata-inside-dind/README.md +++ b/builds/kata-inside-dind/README.md @@ -84,18 +84,18 @@ cat /sys/module/kvm_intel/parameters/nested ### Environment Variables -| Variable | Default | Description | -| ------------------------------ | -------- | --------------------------------------------- | -| `DEBIAN_VERSION` | `13.2` | Base Debian version | -| `KATA_VERSION` | `3.24.0` | Kata Containers version | -| `FIRECRACKER_VERSION` | `1.10.1` | Version of Firecracker VMM to install | -| `KATA_DIND_VERSION` | `0.2.0` | Built image version tag | -| `TZ` | `UTC` | Timezone for the container | -| `KATA_LOGGING_LEVEL` | `info` | Kata logging level (debug, info, warn, error) | -| `KATA_DIND_CPU_LIMIT` | `2.00` | CPU limit in cores | -| `KATA_DIND_MEMORY_LIMIT` | `4G` | Memory limit | -| `KATA_DIND_CPU_RESERVATION` | `0.50` | CPU reservation in cores | -| `KATA_DIND_MEMORY_RESERVATION` | `1G` | Memory reservation | +| Variable | Default | Description | +| ------------------------------ | ----------- | --------------------------------------------- | +| `DEBIAN_VERSION` | `13.2-slim` | Base Debian version | +| `KATA_VERSION` | `3.24.0` | Kata Containers version | +| `FIRECRACKER_VERSION` | `1.10.1` | Version of Firecracker VMM to install | +| `KATA_DIND_VERSION` | `0.2.0` | Built image version tag | +| `TZ` | `UTC` | Timezone for the container | +| `KATA_LOGGING_LEVEL` | `info` | Kata logging level (debug, info, warn, error) | +| `KATA_DIND_CPU_LIMIT` | `2.00` | CPU limit in cores | +| `KATA_DIND_MEMORY_LIMIT` | `4G` | Memory limit | +| `KATA_DIND_CPU_RESERVATION` | `0.50` | CPU reservation in cores | +| `KATA_DIND_MEMORY_RESERVATION` | `1G` | Memory reservation | ## Usage Examples diff --git a/builds/kata-inside-dind/README.zh.md b/builds/kata-inside-dind/README.zh.md index d104540..4980bdb 100644 --- a/builds/kata-inside-dind/README.zh.md +++ b/builds/kata-inside-dind/README.zh.md @@ -84,18 +84,18 @@ cat /sys/module/kvm_intel/parameters/nested ### 环境变量 -| 变量 | 默认值 | 说明 | -| ------------------------------ | -------- | ----------------------------------------- | -| `DEBIAN_VERSION` | `13.2` | 基础 Debian 版本 | -| `KATA_VERSION` | `3.24.0` | Kata Containers 版本 | -| `FIRECRACKER_VERSION` | `1.10.1` | 要安装的 Firecracker VMM 版本 | -| `KATA_DIND_VERSION` | `0.2.0` | 构建的镜像版本标签 | -| `TZ` | `UTC` | 容器的时区 | -| `KATA_LOGGING_LEVEL` | `info` | Kata 日志级别（debug、info、warn、error） | -| `KATA_DIND_CPU_LIMIT` | `2.00` | CPU 限制（核心数） | -| `KATA_DIND_MEMORY_LIMIT` | `4G` | 内存限制 | -| `KATA_DIND_CPU_RESERVATION` | `0.50` | CPU 预留（核心数） | -| `KATA_DIND_MEMORY_RESERVATION` | `1G` | 内存预留 | +| 变量 | 默认值 | 说明 | +| ------------------------------ | ----------- | ----------------------------------------- | +| `DEBIAN_VERSION` | `13.2-slim` | 基础 Debian 版本 | +| `KATA_VERSION` | `3.24.0` | Kata Containers 版本 | +| `FIRECRACKER_VERSION` | `1.10.1` | 要安装的 Firecracker VMM 版本 | +| `KATA_DIND_VERSION` | `0.2.0` | 构建的镜像版本标签 | +| `TZ` | `UTC` | 容器的时区 | +| `KATA_LOGGING_LEVEL` | `info` | Kata 日志级别（debug、info、warn、error） | +| `KATA_DIND_CPU_LIMIT` | `2.00` | CPU 限制（核心数） | +| `KATA_DIND_MEMORY_LIMIT` | `4G` | 内存限制 | +| `KATA_DIND_CPU_RESERVATION` | `0.50` | CPU 预留（核心数） | +| `KATA_DIND_MEMORY_RESERVATION` | `1G` | 内存预留 | ## 使用示例 diff --git a/builds/kata-inside-dind/docker-compose.yaml b/builds/kata-inside-dind/docker-compose.yaml index 873f131..a0f8dbb 100644 --- a/builds/kata-inside-dind/docker-compose.yaml +++ b/builds/kata-inside-dind/docker-compose.yaml @@ -18,7 +18,7 @@ services: context: . dockerfile: Dockerfile args: - DEBIAN_VERSION: ${DEBIAN_VERSION:-13.2} + DEBIAN_VERSION: ${DEBIAN_VERSION:-13.2-slim} KATA_VERSION: ${KATA_VERSION:-3.24.0} FIRECRACKER_VERSION: ${FIRECRACKER_VERSION:-1.14.0} privileged: true diff --git a/builds/kata-inside-dind/dockerd-entrypoint.sh b/builds/kata-inside-dind/dockerd-entrypoint.sh index f1385ee..94b814e 100644 --- a/builds/kata-inside-dind/dockerd-entrypoint.sh +++ b/builds/kata-inside-dind/dockerd-entrypoint.sh @@ -78,6 +78,15 @@ if [ -f /etc/kata-containers/configuration-fc.toml ] && [ -x /usr/local/bin/fire sed -i 's|path = ".*firecracker"|path = "/usr/local/bin/firecracker"|g' /etc/kata-containers/configuration-fc.toml || true fi fi + + # Update jailer path if available + if [ -x /usr/local/bin/jailer ]; then + if ! grep -q "jailer_path = \"/usr/local/bin/jailer\"" /etc/kata-containers/configuration-fc.toml 2>/dev/null; then + if [ -w /etc/kata-containers/configuration-fc.toml ]; then + sed -i 's|jailer_path = ".*jailer"|jailer_path = "/usr/local/bin/jailer"|g' /etc/kata-containers/configuration-fc.toml || true + fi + fi + fi fi # Enable debug logging if requested diff --git a/src/libsql/.env.example b/src/libsql/.env.example new file mode 100644 index 0000000..ad41aeb --- /dev/null +++ b/src/libsql/.env.example @@ -0,0 +1,71 @@ +# Global registry prefix (optional, for custom registry mirrors) +# GLOBAL_REGISTRY= + +# libSQL Server version +LIBSQL_VERSION=latest + +# Platform architecture (linux/amd64 or linux/arm64) +# Note: For ARM64 (Apple Silicon), use latest-arm tag or run via Rosetta with linux/amd64 +LIBSQL_PLATFORM=linux/amd64 + +# Timezone +TZ=UTC + +# ==================== Port Configuration ==================== +# HTTP/Hrana API port (client connections) +LIBSQL_HTTP_PORT_OVERRIDE=8080 + +# gRPC port (for replication between primary and replicas) +LIBSQL_GRPC_PORT_OVERRIDE=5001 + +# Replica HTTP port (only used when replica profile is enabled) +LIBSQL_REPLICA_HTTP_PORT_OVERRIDE=8081 + +# Replica gRPC port (only used when replica profile is enabled) +LIBSQL_REPLICA_GRPC_PORT_OVERRIDE=5002 + +# ==================== Node Configuration ==================== +# Node type: primary, replica, or standalone +# - primary: Main database instance, accepts writes +# - replica: Read-only replica, replicates from primary +# - standalone: Single instance without replication +LIBSQL_NODE=primary + +# Database file name (stored in /var/lib/sqld by default) +LIBSQL_DB_PATH=iku.db + +# HTTP listen address (internal, usually no need to change) +LIBSQL_HTTP_LISTEN_ADDR=0.0.0.0:8080 + +# gRPC listen address (internal, usually no need to change) +LIBSQL_GRPC_LISTEN_ADDR=0.0.0.0:5001 + +# ==================== Replication Configuration ==================== +# Primary URL for replica instances (format: http://host:port or https://host:port) +# Only required when LIBSQL_NODE=replica +# Example for Docker Compose: http://libsql:5001 +LIBSQL_PRIMARY_URL=http://libsql:5001 + +# ==================== Authentication (Optional) ==================== +# HTTP basic authentication (format: basic:base64(username:password)) +# Example: basic:dXNlcjpwYXNz (for user:pass) +# LIBSQL_HTTP_AUTH= + +# Path to JWT key file for authentication (mounted into container) +# LIBSQL_AUTH_JWT_KEY_FILE= + +# JWT key directly as environment variable (alternative to file) +# LIBSQL_AUTH_JWT_KEY= + +# ==================== Resource Limits ==================== +# Primary instance resource limits +LIBSQL_CPU_LIMIT=1.0 +LIBSQL_MEMORY_LIMIT=512M +LIBSQL_CPU_RESERVATION=0.5 +LIBSQL_MEMORY_RESERVATION=256M + +# Replica instance resource limits (when replica profile is enabled) +LIBSQL_REPLICA_CPU_LIMIT=1.0 +LIBSQL_REPLICA_MEMORY_LIMIT=512M +LIBSQL_REPLICA_CPU_RESERVATION=0.5 +LIBSQL_REPLICA_MEMORY_RESERVATION=256M diff --git a/src/libsql/README.md b/src/libsql/README.md new file mode 100644 index 0000000..4c1c8c1 --- /dev/null +++ b/src/libsql/README.md @@ -0,0 +1,228 @@ +# libSQL Server + +[中文说明](README.zh.md) + +## Introduction + +libSQL is an open-source fork of SQLite optimized for edge deployments and serverless architectures. It offers SQLite compatibility with additional features like primary-replica replication, built-in HTTP/WebSocket API (Hrana protocol), and is designed for distributed database scenarios. + +**Key Features:** + +- 100% SQLite compatible +- Primary-replica replication support +- Built-in HTTP and WebSocket APIs +- Edge-optimized for low latency +- Open-source and extensible + +**Official Resources:** + +- GitHub: +- Documentation: +- Docker Hub: + +## Quick Start + +### 1. Basic Usage (Primary Instance) + +```bash +cd src/libsql +docker compose up -d +``` + +The database will be available at: + +- HTTP/Hrana API: +- gRPC (for replication): localhost:5001 + +### 2. With Replica Instance + +To enable replication, start with the `replica` profile: + +```bash +docker compose --profile replica up -d +``` + +This will start: + +- Primary instance on ports 8080 (HTTP) and 5001 (gRPC) +- Replica instance on ports 8081 (HTTP) and 5002 (gRPC) + +### 3. Accessing the Database + +You can connect to libSQL using: + +**Via HTTP API:** + +```bash +# Create a table +curl -X POST http://localhost:8080 \ + -H "Content-Type: application/json" \ + -d '{"statements": ["CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"]}' + +# Insert data +curl -X POST http://localhost:8080 \ + -H "Content-Type: application/json" \ + -d '{"statements": ["INSERT INTO users (name) VALUES ('\''Alice'\'')"]}' + +# Query data +curl -X POST http://localhost:8080 \ + -H "Content-Type: application/json" \ + -d '{"statements": ["SELECT * FROM users"]}' +``` + +**Via libSQL CLI (if installed):** + +```bash +libsql client http://localhost:8080 +``` + +## Configuration + +### Environment Variables + +Key environment variables (see `.env.example` for full list): + +| Variable | Default | Description | +| --------------------------- | -------------------- | ------------------------------------------------ | +| `LIBSQL_VERSION` | `latest` | libSQL server version | +| `LIBSQL_HTTP_PORT_OVERRIDE` | `8080` | HTTP API port | +| `LIBSQL_GRPC_PORT_OVERRIDE` | `5001` | gRPC port for replication | +| `LIBSQL_NODE` | `primary` | Node type: `primary`, `replica`, or `standalone` | +| `LIBSQL_DB_PATH` | `iku.db` | Database file name | +| `LIBSQL_PRIMARY_URL` | `http://libsql:5001` | Primary URL for replica nodes | +| `TZ` | `UTC` | Timezone | + +### Authentication (Optional) + +To enable authentication, uncomment and configure these variables: + +**HTTP Basic Auth:** + +```bash +# Generate base64 encoded credentials +echo -n "username:password" | base64 +# Result: dXNlcm5hbWU6cGFzc3dvcmQ= + +# Set in .env +LIBSQL_HTTP_AUTH=basic:dXNlcm5hbWU6cGFzc3dvcmQ= +``` + +**JWT Authentication:** + +```bash +# Option 1: Using key file +LIBSQL_AUTH_JWT_KEY_FILE=/path/to/jwt-key.pem + +# Option 2: Using key directly +LIBSQL_AUTH_JWT_KEY=your-jwt-key-here +``` + +### Platform Support + +- **x86-64:** Use `LIBSQL_PLATFORM=linux/amd64` (default) +- **ARM64 (Apple Silicon):** + - Use `LIBSQL_VERSION=latest-arm` for native ARM images + - Or use `LIBSQL_PLATFORM=linux/amd64` to run via Rosetta + +## Data Persistence + +Database files are stored in a Docker named volume: + +- Volume: `libsql_data` +- Container path: `/var/lib/sqld` + +To backup your database: + +```bash +# Copy database file from container +docker compose cp libsql:/var/lib/sqld/iku.db ./backup.db +``` + +## Resource Limits + +Default resource allocations per instance: + +- CPU: 0.5-1.0 cores +- Memory: 256M-512M + +Adjust in `.env` file: + +```bash +LIBSQL_CPU_LIMIT=2.0 +LIBSQL_MEMORY_LIMIT=1G +``` + +## Replication Architecture + +libSQL supports primary-replica replication: + +1. **Primary Instance:** Accepts reads and writes +2. **Replica Instance(s):** Read-only, replicates from primary via gRPC + +To add a replica: + +```bash +# Start with replica profile +docker compose --profile replica up -d +``` + +Replicas connect to the primary using `LIBSQL_PRIMARY_URL` and stay synchronized automatically. + +## Common Operations + +### Check Server Health + +```bash +curl http://localhost:8080/health +``` + +### View Logs + +```bash +docker compose logs -f libsql +``` + +### Restart Service + +```bash +docker compose restart libsql +``` + +### Stop and Remove + +```bash +docker compose down +# To remove volumes as well +docker compose down -v +``` + +## Troubleshooting + +### Connection Refused + +- Verify the service is running: `docker compose ps` +- Check logs: `docker compose logs libsql` +- Ensure ports are not in use: `netstat -an | grep 8080` + +### Replica Not Syncing + +- Verify `LIBSQL_PRIMARY_URL` is correct +- Check primary instance is healthy and accessible +- Review replica logs for connection errors + +### Performance Issues + +- Increase resource limits in `.env` +- Consider using SSD for volume storage +- Enable query logging for optimization + +## Security Notes + +- **Default Setup:** No authentication enabled - suitable for development only +- **Production:** Always enable authentication (HTTP Basic or JWT) +- **Network:** Consider using Docker networks or reverse proxy for external access +- **Secrets:** Never commit `.env` with credentials to version control + +## License + +libSQL is licensed under the MIT License. See the [official repository](https://github.com/tursodatabase/libsql) for details. diff --git a/src/libsql/README.zh.md b/src/libsql/README.zh.md new file mode 100644 index 0000000..b9003a0 --- /dev/null +++ b/src/libsql/README.zh.md @@ -0,0 +1,228 @@ +# libSQL Server + +[English Documentation](README.md) + +## 简介 + +libSQL 是 SQLite 的开源分支，针对边缘部署和无服务器架构进行了优化。它提供与 SQLite 的完全兼容性，同时增加了主从复制、内置 HTTP/WebSocket API（Hrana 协议）等功能，专为分布式数据库场景设计。 + +**核心特性：** + +- 100% SQLite 兼容 +- 支持主从复制 +- 内置 HTTP 和 WebSocket API +- 边缘优化，低延迟 +- 开源可扩展 + +**官方资源：** + +- GitHub： +- 文档： +- Docker Hub： + +## 快速开始 + +### 1. 基本用法（主实例） + +```bash +cd src/libsql +docker compose up -d +``` + +数据库将在以下端口可用： + +- HTTP/Hrana API： +- gRPC（用于复制）：localhost:5001 + +### 2. 启用副本实例 + +要启用复制，使用 `replica` profile 启动： + +```bash +docker compose --profile replica up -d +``` + +这将启动： + +- 主实例，端口 8080（HTTP）和 5001（gRPC） +- 副本实例，端口 8081（HTTP）和 5002（gRPC） + +### 3. 访问数据库 + +可以通过以下方式连接到 libSQL： + +**通过 HTTP API：** + +```bash +# 创建表 +curl -X POST http://localhost:8080 \ + -H "Content-Type: application/json" \ + -d '{"statements": ["CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"]}' + +# 插入数据 +curl -X POST http://localhost:8080 \ + -H "Content-Type: application/json" \ + -d '{"statements": ["INSERT INTO users (name) VALUES ('\''Alice'\'')"]}' + +# 查询数据 +curl -X POST http://localhost:8080 \ + -H "Content-Type: application/json" \ + -d '{"statements": ["SELECT * FROM users"]}' +``` + +**通过 libSQL CLI（如已安装）：** + +```bash +libsql client http://localhost:8080 +``` + +## 配置说明 + +### 环境变量 + +主要环境变量（完整列表请参见 `.env.example`）： + +| 变量名 | 默认值 | 说明 | +| --------------------------- | -------------------- | ---------------------------------------------- | +| `LIBSQL_VERSION` | `latest` | libSQL 服务器版本 | +| `LIBSQL_HTTP_PORT_OVERRIDE` | `8080` | HTTP API 端口 | +| `LIBSQL_GRPC_PORT_OVERRIDE` | `5001` | gRPC 复制端口 | +| `LIBSQL_NODE` | `primary` | 节点类型：`primary`、`replica` 或 `standalone` | +| `LIBSQL_DB_PATH` | `iku.db` | 数据库文件名 | +| `LIBSQL_PRIMARY_URL` | `http://libsql:5001` | 副本节点的主节点 URL | +| `TZ` | `UTC` | 时区 | + +### 身份验证（可选） + +要启用身份验证，请取消注释并配置以下变量： + +**HTTP 基本认证：** + +```bash +# 生成 base64 编码的凭据 +echo -n "username:password" | base64 +# 结果：dXNlcm5hbWU6cGFzc3dvcmQ= + +# 在 .env 中设置 +LIBSQL_HTTP_AUTH=basic:dXNlcm5hbWU6cGFzc3dvcmQ= +``` + +**JWT 认证：** + +```bash +# 方式 1：使用密钥文件 +LIBSQL_AUTH_JWT_KEY_FILE=/path/to/jwt-key.pem + +# 方式 2：直接使用密钥 +LIBSQL_AUTH_JWT_KEY=your-jwt-key-here +``` + +### 平台支持 + +- **x86-64：** 使用 `LIBSQL_PLATFORM=linux/amd64`（默认） +- **ARM64（Apple Silicon）：** + - 使用 `LIBSQL_VERSION=latest-arm` 获取原生 ARM 镜像 + - 或使用 `LIBSQL_PLATFORM=linux/amd64` 通过 Rosetta 运行 + +## 数据持久化 + +数据库文件存储在 Docker 命名卷中： + +- 卷名：`libsql_data` +- 容器路径：`/var/lib/sqld` + +备份数据库： + +```bash +# 从容器复制数据库文件 +docker compose cp libsql:/var/lib/sqld/iku.db ./backup.db +``` + +## 资源限制 + +每个实例的默认资源分配： + +- CPU：0.5-1.0 核心 +- 内存：256M-512M + +在 `.env` 文件中调整： + +```bash +LIBSQL_CPU_LIMIT=2.0 +LIBSQL_MEMORY_LIMIT=1G +``` + +## 复制架构 + +libSQL 支持主从复制： + +1. **主实例：** 接受读写操作 +2. **副本实例：** 只读，通过 gRPC 从主实例复制 + +添加副本： + +```bash +# 使用 replica profile 启动 +docker compose --profile replica up -d +``` + +副本使用 `LIBSQL_PRIMARY_URL` 连接到主实例，并自动保持同步。 + +## 常用操作 + +### 检查服务器健康状态 + +```bash +curl http://localhost:8080/health +``` + +### 查看日志 + +```bash +docker compose logs -f libsql +``` + +### 重启服务 + +```bash +docker compose restart libsql +``` + +### 停止并删除 + +```bash +docker compose down +# 同时删除卷 +docker compose down -v +``` + +## 故障排查 + +### 连接被拒绝 + +- 验证服务正在运行：`docker compose ps` +- 检查日志：`docker compose logs libsql` +- 确保端口未被占用：`netstat -an | grep 8080` + +### 副本未同步 + +- 验证 `LIBSQL_PRIMARY_URL` 是否正确 +- 检查主实例是否健康且可访问 +- 查看副本日志以查找连接错误 + +### 性能问题 + +- 在 `.env` 中增加资源限制 +- 考虑为卷存储使用 SSD +- 启用查询日志以进行优化 + +## 安全注意事项 + +- **默认设置：** 未启用身份验证 - 仅适用于开发环境 +- **生产环境：** 始终启用身份验证（HTTP Basic 或 JWT） +- **网络：** 考虑使用 Docker 网络或反向代理进行外部访问 +- **密钥：** 切勿将包含凭据的 `.env` 提交到版本控制 + +## 许可证 + +libSQL 采用 MIT 许可证。详情请参见[官方仓库](https://github.com/tursodatabase/libsql)。 diff --git a/src/libsql/docker-compose.yaml b/src/libsql/docker-compose.yaml new file mode 100644 index 0000000..5e52954 --- /dev/null +++ b/src/libsql/docker-compose.yaml @@ -0,0 +1,87 @@ +# Docker Compose configuration for libSQL Server +# libSQL is an open-source fork of SQLite optimized for edge deployments +# Supports primary-replica replication and serverless architectures + +x-defaults: &defaults + restart: unless-stopped + logging: + driver: json-file + options: + max-size: 100m + max-file: "3" + +services: + libsql: + <<: *defaults + image: ${GHCR_IO_REGISTRY:-ghcr.io}/tursodatabase/libsql-server:${LIBSQL_VERSION:-latest} + platform: ${LIBSQL_PLATFORM:-linux/amd64} + ports: + - "${LIBSQL_HTTP_PORT_OVERRIDE:-8080}:8080" # HTTP/Hrana API port + - "${LIBSQL_GRPC_PORT_OVERRIDE:-5001}:5001" # gRPC port for replication + volumes: + - libsql_data:/var/lib/sqld + environment: + - TZ=${TZ:-UTC} + - SQLD_NODE=${LIBSQL_NODE:-primary} + - SQLD_DB_PATH=${LIBSQL_DB_PATH:-iku.db} + - SQLD_HTTP_LISTEN_ADDR=${LIBSQL_HTTP_LISTEN_ADDR:-0.0.0.0:8080} + - SQLD_GRPC_LISTEN_ADDR=${LIBSQL_GRPC_LISTEN_ADDR:-0.0.0.0:5001} + # Authentication (optional, uncomment to enable) + # - SQLD_HTTP_AUTH=${LIBSQL_HTTP_AUTH:-} + # - SQLD_AUTH_JWT_KEY_FILE=${LIBSQL_AUTH_JWT_KEY_FILE:-} + # - SQLD_AUTH_JWT_KEY=${LIBSQL_AUTH_JWT_KEY:-} + healthcheck: + test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 10s + deploy: + resources: + limits: + cpus: ${LIBSQL_CPU_LIMIT:-1.0} + memory: ${LIBSQL_MEMORY_LIMIT:-512M} + reservations: + cpus: ${LIBSQL_CPU_RESERVATION:-0.5} + memory: ${LIBSQL_MEMORY_RESERVATION:-256M} + + # Replica instance (optional, use with profile) + libsql-replica: + <<: *defaults + image: ${GHCR_IO_REGISTRY:-ghcr.io}/tursodatabase/libsql-server:${LIBSQL_VERSION:-latest} + platform: ${LIBSQL_PLATFORM:-linux/amd64} + profiles: + - replica + ports: + - "${LIBSQL_REPLICA_HTTP_PORT_OVERRIDE:-8081}:8080" + - "${LIBSQL_REPLICA_GRPC_PORT_OVERRIDE:-5002}:5001" + volumes: + - libsql_replica_data:/var/lib/sqld + environment: + - TZ=${TZ:-UTC} + - SQLD_NODE=replica + - SQLD_PRIMARY_URL=${LIBSQL_PRIMARY_URL:-http://libsql:5001} + - SQLD_DB_PATH=${LIBSQL_DB_PATH:-iku.db} + - SQLD_HTTP_LISTEN_ADDR=${LIBSQL_HTTP_LISTEN_ADDR:-0.0.0.0:8080} + - SQLD_GRPC_LISTEN_ADDR=${LIBSQL_GRPC_LISTEN_ADDR:-0.0.0.0:5001} + healthcheck: + test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 10s + depends_on: + libsql: + condition: service_healthy + deploy: + resources: + limits: + cpus: ${LIBSQL_REPLICA_CPU_LIMIT:-1.0} + memory: ${LIBSQL_REPLICA_MEMORY_LIMIT:-512M} + reservations: + cpus: ${LIBSQL_REPLICA_CPU_RESERVATION:-0.5} + memory: ${LIBSQL_REPLICA_MEMORY_RESERVATION:-256M} + +volumes: + libsql_data: + libsql_replica_data: