Docker Ecosystem
Relevant source files
The following files were used as context for generating this wiki page:
The Docker Ecosystem in CCS provides a containerized environment for deploying the CCS Dashboard and CLIProxy services. It is designed to offer a consistent, persistent, and secure runtime that can be managed locally or deployed to remote hosts via SSH. The ecosystem centers around an integrated image that bundles core services while encouraging the use of sibling containers for specific AI CLI tools.
Sources: docker/README.md:1-20, src/docker/docker-assets.ts:7-10
Architecture and Components
The ecosystem utilizes a multi-layered architecture where a primary container (ccs-cliproxy) runs multiple internal services managed by a supervisor process. This container is connected to a dedicated Docker network, enabling secure communication with other tools.
Integrated Container Internal Services
The ccs:latest image uses supervisord to manage two primary processes within a single container:
- CCS Dashboard: A web-based interface for managing profiles and monitoring system health, typically exposed on port 3000.
- CLIProxy: An OAuth proxy service that routes AI requests, typically exposed on port 8317.
Sources: docker/README.md:65-75, src/docker/docker-assets.ts:13-16
Process Management Flow
The following diagram illustrates how the ccs-cliproxy container initializes and manages its internal services.
The container uses entrypoint-integrated.sh to start supervisord, which subsequently launches the dashboard and proxy.
Sources: src/docker/docker-assets.ts:46-55, tests/unit/docker/docker-release-workflow-context.test.ts:10-18
Network and Connectivity Contract
CCS establishes a stable network contract to ensure that external applications and sibling containers can reliably communicate with the services.
Stable Network Identifiers
| Resource | Stable Name | Description |
|---|---|---|
| Network | ccs-net | The primary network for inter-container communication. |
| Service DNS | ccs | Internal DNS name used to resolve the CCS container within ccs-net. |
| CLIProxy Port | 8317 | Port for OAuth proxy and OpenAI-compatible routing. |
| Dashboard Port | 3000 | Port for the web-based management interface. |
Sources: docker/README.md:162-171, src/docker/docker-assets.ts:7-11
Connectivity Architecture
Sibling containers (e.g., claude-code, gemini-cli) are intended to run independently and connect to the ccs service via the ccs-net network.
This architecture keeps the primary image lightweight while allowing independent versioning of AI tools.
Sources: docker/README.md:33-40, docker/README.md:174-185
Deployment and Execution Logic
The DockerExecutor class manages the lifecycle of the Docker stack, supporting both local and remote operations.
Remote Staging and Execution
For remote deployments, CCS stages local assets to the target host before execution.
- Stage Assets: Copies
compose.yaml,Dockerfile.integrated,supervisord.conf, andentrypoint-integrated.shto~/.ccs/dockeron the remote host viascp. - Remote Execution: Executes Docker commands (up, down, status) over
sshusing the staged files.
Sources: src/docker/docker-executor.ts:182-205, src/docker/docker-assets.ts:46-55
Command Reference
The ccs docker command suite provides high-level abstractions for managing the stack:
| Command | Action | Implementation Detail |
|---|---|---|
ccs docker up | Starts the stack | Uses docker compose up -d --build with environment variable injection. |
ccs docker down | Stops the stack | Executes docker compose down. |
ccs docker logs | Retrieves logs | Tails /var/log/ccs/ccs-dashboard.log and cliproxy.log. |
ccs docker status | Checks health | Aggregates docker compose ps and supervisorctl status. |
Sources: src/docker/docker-executor.ts:114-150, src/docker/docker-assets.ts:13-16
Security and Auth Configuration
Docker deployments include specific security mechanisms, particularly for remote access and API key rotation.
Dashboard Authentication
When the dashboard is accessed from a non-localhost address, it returns 403 Forbidden unless authentication is explicitly enabled. Users must configure CCS_DASHBOARD_AUTH_ENABLED and associated credentials.
Sources: docker/README.md:86-105
API Key Rotation Logic
CCS manages a grace period for CLIProxy API keys during upgrades.
If a legacy key is detected, CCS maintains it alongside the new key for 14 days by default. Users can finalize this rotation manually using ccs docker finalize-key-rotation.
Sources: docker/README.md:118-125, src/commands/docker/show-key-subcommand.ts:55-75
Summary
The CCS Docker Ecosystem provides a robust, process-supervised environment that encapsulates the CCS Dashboard and CLIProxy. By defining a stable network contract (ccs-net) and providing the ccs docker command suite, it facilitates seamless deployment across local and remote environments while maintaining high standards for security and service isolation.
Sources: docker/README.md:1-20, src/docker/docker-executor.ts:20-40