mirror of https://github.com/tiennm99/ccs.git synced 2026-07-15 18:21:09 +00:00

Files

T

kaitrannttandopastorello b38641002f fix(docker): address security and reproducibility issues

Fixes from maintainer review:

.dockerignore:
- Add .env* files to prevent secret leakage (CRITICAL)
- Add tests/, docs/, IDE files to reduce build context
- Add organized comments for maintainability

Dockerfile:
- Pin bun version (ARG BUN_VERSION=1.2.2) for reproducible builds
- Add build artifact validation step
- Add npm cache clean to reduce image size
- Add section comments for readability

docker-compose.yml:
- Add grok_home volume for grok-cli persistence
- Add start_period to healthcheck for slow starts
- Add resource limits (1G RAM, 2 CPUs) with reservations
- Add documentation comments

entrypoint.sh:
- Improve chown error handling with warning message
- Add usage help when no command provided

README.md:
- Add Resource Limits section with examples
- Add Graceful Shutdown documentation
- Add Troubleshooting section (permissions, ports, restart loops)
- Add Security Notes section
- Update persistence docs to include grok-cli

Co-authored-by: opastorello <nicolas@pastorello-lab.com.br>

2026-01-18 08:10:44 -05:00

4.7 KiB

Raw Blame History

CCS Dashboard - Docker

Run the CCS Config Dashboard in Docker.

Persistent config, restart on reboot.

Back to README

Quick Start (Docker Run)

docker build -f docker/Dockerfile -t ccs-dashboard:latest .
docker run -d \
  --name ccs-dashboard \
  --restart unless-stopped \
  -p 3000:3000 \
  -p 8317:8317 \
  -e CCS_PORT=3000 \
  -v ccs_home:/home/node/.ccs \
  ccs-dashboard:latest

Open http://localhost:3000 (Dashboard).

CCS also starts CLIProxy on http://localhost:8317 (used by Dashboard features and OAuth providers).

Environment Variables

Common CCS environment variables (from the docs):

Docs: Environment variables
CCS_CONFIG: override config file path
CCS_UNIFIED_CONFIG=1: force unified YAML config loader
CCS_MIGRATE=1: trigger config migration
CCS_SKIP_MIGRATION=1: skip migrations
CCS_DEBUG=1: enable verbose logs
NO_COLOR=1: disable ANSI colors
CCS_SKIP_PREFLIGHT=1: skip API key validation checks
CCS_WEBSEARCH_SKIP=1: skip WebSearch hook integration
Proxy: CCS_PROXY_HOST, CCS_PROXY_PORT, CCS_PROXY_PROTOCOL, CCS_PROXY_AUTH_TOKEN, CCS_PROXY_TIMEOUT, CCS_PROXY_FALLBACK_ENABLED, CCS_ALLOW_SELF_SIGNED

Example (passing env vars to the running container):

docker run -d \
  --name ccs-dashboard \
  --restart unless-stopped \
  -p 3000:3000 \
  -p 8317:8317 \
  -e CCS_PORT=3000 \
  -e CCS_DEBUG=1 \
  -e NO_COLOR=1 \
  -e CCS_PROXY_HOST="proxy.example.com" \
  -e CCS_PROXY_PORT=443 \
  -e CCS_PROXY_PROTOCOL="https" \
  -v ccs_home:/home/node/.ccs \
  ccs-dashboard:latest

Useful Commands

docker logs -f ccs-dashboard
docker stop ccs-dashboard
docker start ccs-dashboard
docker rm -f ccs-dashboard

Docker Compose (Optional)

Using the included docker/docker-compose.yml:

docker-compose -f docker/docker-compose.yml up --build -d
docker-compose -f docker/docker-compose.yml logs -f

Stop:

docker-compose -f docker/docker-compose.yml down

Persistence

CCS stores data in /home/node/.ccs inside the container.
The examples use a named volume (ccs_home) to persist that data.
Compose also persists /home/node/.claude, /home/node/.opencode, and /home/node/.grok-cli via named volumes.

Resource Limits

For production deployments, limit container resources:

docker run -d \
  --name ccs-dashboard \
  --restart unless-stopped \
  --memory=1g \
  --cpus=2 \
  -p 3000:3000 \
  -p 8317:8317 \
  -v ccs_home:/home/node/.ccs \
  ccs-dashboard:latest

Docker Compose includes default limits (1GB RAM, 2 CPUs). Adjust in docker-compose.yml under deploy.resources.

Graceful Shutdown

CCS handles SIGTERM gracefully. When stopping the container:

docker stop ccs-dashboard        # Sends SIGTERM, waits 10s, then SIGKILL
docker stop -t 30 ccs-dashboard  # Wait 30s for graceful shutdown

The init: true in docker-compose.yml ensures proper signal forwarding.

Troubleshooting

Permission Errors (EACCES)

If you see permission errors on startup:

# Check volume permissions
docker exec ccs-dashboard ls -la /home/node/.ccs

# Fix by recreating volumes
docker-compose down -v
docker-compose up -d

Port Already in Use

# Check what's using the port
lsof -i :3000
lsof -i :8317

# Use different ports
docker run -p 4000:3000 -p 9317:8317 ...

# Or with compose
CCS_DASHBOARD_PORT=4000 CCS_CLIPROXY_PORT=9317 docker-compose up -d

Container Keeps Restarting

# Check logs for errors
docker logs ccs-dashboard --tail 50

# Check container health
docker inspect ccs-dashboard --format='{{.State.Health.Status}}'

Debug Mode

Enable verbose logging:

docker run -e CCS_DEBUG=1 ...

Examples: Claude + Gemini inside Docker

Open a shell inside the running container:

docker exec -it ccs-dashboard bash

Claude (non-interactive / print mode):

docker exec -it ccs-dashboard claude -p "Hello from Docker"

Gemini (one-shot prompt):

docker exec -it ccs-dashboard gemini "Hello from Docker"

If you need to configure credentials, do it according to each CLI's docs:

docker exec -it ccs-dashboard claude --help
docker exec -it ccs-dashboard gemini --help

Security Notes

Secrets: For sensitive values like CCS_PROXY_AUTH_TOKEN, consider using Docker secrets or a .env file (not committed to git).
Network: The container exposes ports 3000 and 8317. In production, use a reverse proxy (nginx, traefik) with TLS.
Updates: Regularly rebuild the image to get security patches: docker-compose build --pull

4.7 KiB Raw Blame History