Skip to main content
Cerbos provides official container images for running the Policy Decision Point (PDP) in containerized environments. Images are available from both GitHub Container Registry and Docker Hub.

​
Quick Start

Run Cerbos with the default configuration: 
docker run --rm --name cerbos -p 3592:3592 ghcr.io/cerbos/cerbos:latest
This starts Cerbos with:
  • HTTP API on port 3592
  • gRPC API on port 3593 (not exposed in this example)
  • Default policy directory at /policies

​
Container Images

Cerbos images are published to two registries:
  • GitHub Container Registry: ghcr.io/cerbos/cerbos:latest
  • Docker Hub: docker.io/cerbos/cerbos:latest
Both registries contain identical images. Use version tags for production deployments: 
docker pull ghcr.io/cerbos/cerbos:0.52.0

​
Image Verification

Cerbos images are signed using Sigstore and can be verified with Cosign: 
cosign verify \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity="https://github.com/cerbos/cerbos/.github/workflows/release.yaml@refs/tags/v0.52.0" \
  ghcr.io/cerbos/cerbos:0.52.0

​
Custom Configuration

1

Create directory structure

Create a directory to hold your configuration and policies:
mkdir -p cerbos-quickstart/policies
2

Create configuration file

Create a custom Cerbos configuration file:
cat > cerbos-quickstart/.cerbos.yaml <<EOF
server:
  httpListenAddr: ":3592"
  grpcListenAddr: ":3593"

storage:
  driver: "disk"
  disk:
    directory: /quickstart/policies
    watchForChanges: true
EOF
3

Launch container with custom config

Mount your directory and use the custom configuration:
docker run --rm --name cerbos -d \
  -v $(pwd)/cerbos-quickstart:/quickstart \
  -p 3592:3592 \
  -p 3593:3593 \
  ghcr.io/cerbos/cerbos:latest server --config=/quickstart/.cerbos.yaml

​
Container Details

The Cerbos container image is built on Alpine Linux and includes:
  • Base Image: alpine:3.16 with CA certificates
  • Exposed Ports:
    • 3592 - HTTP API
    • 3593 - gRPC API
  • Volumes:
    • /policies - Default policy directory
    • /tmp - Temporary files
    • /.cache - Cache directory
  • Entrypoint: /cerbos
  • Default Command: server
  • Health Check: Built-in healthcheck on /cerbos healthcheck endpoint

​
Environment Variables

The container supports configuration via environment variables: 
docker run --rm --name cerbos \
  -e CERBOS_CONFIG="__default__" \
  -p 3592:3592 \
  ghcr.io/cerbos/cerbos:latest
Set CERBOS_NO_TELEMETRY=1 to disable telemetry collection.

​
Running with Docker Compose

Create a docker-compose.yml file: 
version: '3.8'

services:
  cerbos:
    image: ghcr.io/cerbos/cerbos:latest
    container_name: cerbos
    ports:
      - "3592:3592"
      - "3593:3593"
    volumes:
      - ./policies:/policies:ro
      - ./config/.cerbos.yaml:/config/.cerbos.yaml:ro
    command: server --config=/config/.cerbos.yaml
    restart: unless-stopped
    healthcheck:
      test: ["/cerbos", "healthcheck"]
      interval: 10s
      timeout: 2s
      retries: 2
Start the service: 
docker-compose up -d

​
Verifying the Installation

Check that Cerbos is running: 
curl http://localhost:3592/_cerbos/health

​
Production Considerations

  • Use specific version tags instead of latest
  • Mount policy directories as read-only volumes
  • Configure appropriate resource limits
  • Enable TLS for production deployments
  • Use persistent volumes for policy storage
  • Set up proper logging and monitoring

​
Next Steps