<!-- source: https://deepwiki.com/qhkm/zeptoclaw/12.2-docker-deployment -->

# Docker Deployment

- .github/workflows/docker.yml
- Dockerfile
- deploy/README.md
- landing/zeptoclaw/docs/src/content/docs/guides/deployment.md
- src/cli/daemon.rs
- src/cli/doctor.rs

This page documents ZeptoClaw's Docker deployment architecture, build process, and runtime configuration. It covers the multi-stage `Dockerfile`, the CI/CD pipeline, entrypoint script logic, volume management, and environment variable configuration for containerized deployments.

For general deployment strategies beyond Docker, see [Deployment Options](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Deployment Options) For container-based agent execution within the gateway, see [Container Gateway Mode](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Container Gateway Mode)

## Multi-Stage Build Architecture

ZeptoClaw uses a two-stage Docker build to minimize the final image size while caching dependencies. The builder stage compiles the Rust binary, and the runtime stage produces a minimal Debian-based image with only the necessary runtime dependencies.

### Production Build Flow

The production `Dockerfile` is optimized for final image size and security.

```

```

**Sources:** [Dockerfile1-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L1-L78)

## Builder Stage

The builder stage uses `rust:1.93-slim-trixie` [Dockerfile10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L10-L10) and implements a dependency caching strategy to speed up rebuilds.

### Dependency Caching Strategy

The `Dockerfile` creates dummy source files to build dependencies separately from the application code. This ensures that dependency compilation is cached in a Docker layer and only re-runs when `Cargo.toml` or `Cargo.lock` changes [Dockerfile20-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L20-L31)

**Sources:** [Dockerfile20-41](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L20-L41)

## Runtime Stage

The runtime stage uses `debian:trixie-slim` [Dockerfile46](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L46-L46) as the base and installs only the minimal runtime dependencies needed for ZeptoClaw operation.

### Runtime Dependencies

The image creates a dedicated `zeptoclaw` user with a home directory at `/data` [Dockerfile55](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L55-L55)

**Sources:** [Dockerfile46-56](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L46-L56) [src/cli/doctor.rs101-106](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L101-L106)

## Docker Entrypoint and Daemon

The `docker-entrypoint.sh` script is the primary process manager for the container [Dockerfile74](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L74-L74) It ensures that the persistent volume has the correct permissions before dropping privileges.

### Entrypoint Execution Flow

```

```

### Daemon Supervision

When running in production, the `cmd_daemon` function provides a supervised execution environment. It handles automatic restarts with exponential backoff if the `gateway` component fails [src/cli/daemon.rs67-133](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L67-L133)

- Initial Backoff : 1,000ms src/cli/daemon.rs 14
- Max Backoff : 300,000ms (5 minutes) src/cli/daemon.rs 15
- State Persistence : The daemon writes its status to daemon_state.json via write_state src/cli/daemon.rs 21-42

**Sources:** [Dockerfile61-74](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L61-L74) [src/cli/daemon.rs14-152](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L14-L152)

## CI/CD and Deployment

ZeptoClaw uses GitHub Actions to automate image builds and publication to the GitHub Container Registry (GHCR).

### GitHub Actions Workflow

The workflow triggers on version tags (e.g., `v1.0.0`) [.github/workflows/docker.yml3-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/workflows/docker.yml#L3-L5) It extracts metadata for semver tagging [.github/workflows/docker.yml24-32](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/workflows/docker.yml#L24-L32) and pushes the resulting image to `ghcr.io` [.github/workflows/docker.yml17-40](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/workflows/docker.yml#L17-L40)

### Deployment Options

Users can deploy via several methods:

1. Docker Compose : Pre-built templates for single-tenant deploy/README.md 70-79 and multi-tenant deploy/README.md 80-90 setups.
2. PaaS : Native support for Fly.io, Railway, and Render via provided config files deploy/README.md 9-14
3. Setup Script : A one-liner curl -fsSL https://zeptoclaw.com/setup.sh | bash -s -- --docker automates the entire process landing/zeptoclaw/docs/src/content/docs/guides/deployment.md 27-30

**Sources:** [.github/workflows/docker.yml1-41](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/workflows/docker.yml#L1-L41) [deploy/README.md1-113](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L1-L113) [landing/zeptoclaw/docs/src/content/docs/guides/deployment.md1-205](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/guides/deployment.md?plain=1#L1-L205)

## Configuration and Health Checks

### Environment Variables

ZeptoClaw supports `ZEPTOCLAW_*` environment variables to override `config.json` settings [deploy/README.md144-157](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L144-L157)

### Health Monitoring

The container exposes port **9090** for health checks [Dockerfile68](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L68-L68) Additionally, the `zeptoclaw config check` command can be used as a container health check [landing/zeptoclaw/docs/src/content/docs/guides/deployment.md73-76](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/guides/deployment.md?plain=1#L73-L76)

The `run_diagnostics` function in `src/cli/doctor.rs` performs comprehensive system checks, including workspace writability via `check_workspace_writable` and binary presence (e.g., `sh`, `git`) via `check_binary` [src/cli/doctor.rs33-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L33-L140)

### Diagnostics to Code Mapping

The following diagram maps the logical diagnostic checks performed during deployment to their corresponding functions in the `doctor` module.

```

```

**Sources:** [Dockerfile65-68](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L65-L68) [src/cli/doctor.rs33-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L33-L140) [deploy/README.md159-166](https://github.com/qhkm/zeptoclaw/blob/2c743d31/deploy/README.md?plain=1#L159-L166)
