Running Synapse in a container

Synapse is distributed as a container image from the Cerbos distribution repository. Running the image directly covers deployments outside Kubernetes: a single Docker host, docker compose, or any container orchestrator that does not use Helm. For Kubernetes deployments, use the Helm chart instead.

The Quick Start covers end-to-end setup with a policy, an extension and a sample request. Return here once the deployment needs to be customised.

Pull the image

A valid Synapse licence is required to pull the image. If you do not already have one, sign up at cerbos.dev/workshop. Your licence credentials are issued together with the URL of the Cerbos distribution repository, substitute that URL wherever CERBOS_DISTRIBUTION_REPO appears below.

Log in to the Cerbos distribution repository:

$ docker login CERBOS_DISTRIBUTION_REPO --username=YOUR_LICENCE_USER --password=YOUR_LICENCE_KEY

Pull the image:

$ docker pull CERBOS_DISTRIBUTION_REPO/synapse/synapse:latest

For production deployments, pin to a specific version rather than latest so that rolling restarts are deterministic. Your Cerbos account team can confirm the current stable version and the upgrade cadence.

Run Synapse

Start the container with the default configuration. It listens on port 3594 for both HTTP and gRPC traffic on the Cerbos API, and loads any policies found under /policies:

$ docker run --rm --name synapse -p 3594:3594 \
    CERBOS_DISTRIBUTION_REPO/synapse/synapse:latest

This default configuration verifies that the image starts. Deployment requires a configuration file specifying the PDP, policies, and extensions.

Provide a configuration file

Synapse accepts a YAML configuration file passed via the --conf.path flag. The following docker run invocation bind-mounts a working directory into the container and provides a configuration file from it:

$ docker run --rm --name synapse -p 3594:3594 \
    -v $(pwd)/config.yaml:/config/config.yaml:ro \ (1)
    -v $(pwd)/extensions:/extensions:ro \ (2)
    CERBOS_DISTRIBUTION_REPO/synapse/synapse:latest \
    server --conf.path=/config/config.yaml (3)
1 The configuration file. By convention this is mounted at /config/config.yaml, though any path inside the container works as long as --conf.path matches.
2 Directory containing extension source or binaries referenced by extension URLs such as /extensions/my_extension.star. Only required when extensions are configured.
3 The server subcommand starts the Synapse server. --conf.path tells it which configuration file to use.

The contents of the configuration file determine how the embedded Cerbos PDP sources its policies. Two options are supported: fetching them from Cerbos Hub as signed, versioned bundles, or loading them from a directory on the local filesystem. Hub is the recommended option for any deployment beyond local development.

Source policies from Cerbos Hub (recommended)

Cerbos Hub publishes signed policy bundles, applies updates to connected Synapse instances without restarts, and centralises policy authoring and audit history. Configure the embedded PDP with the hub storage driver and a deployment ID, then pass Hub credentials to the container as environment variables. See Connecting Synapse to Cerbos Hub for the complete configuration, including audit log shipping and credential handling.

Source policies from local disk (development only)

For local iteration, loading policies from a bind-mounted directory removes the Hub round trip and applies changes as soon as files are saved. The Quick Start uses this approach. It is not suitable for production.

server:
  listenAddress: ":3594"

pdp:
  inProcess:
    storage:
      driver: "disk"
      disk:
        directory: /policies
        watchForChanges: true (1)
1 When set to true, the embedded PDP reloads policies whenever the files in the mounted directory change. Useful during development.

Add a bind mount for the policies directory to the docker run command:

$ docker run --rm --name synapse -p 3594:3594 \
    -v $(pwd)/config.yaml:/config/config.yaml:ro \
    -v $(pwd)/policies:/policies:ro \
    -v $(pwd)/extensions:/extensions:ro \
    CERBOS_DISTRIBUTION_REPO/synapse/synapse:latest \
    server --conf.path=/config/config.yaml

See Configuration for the Synapse-specific configuration schema, and the Cerbos PDP configuration documentation for the options available inside the pdp.inProcess block (TLS, observability, audit backends, schema enforcement).

Route to an external Cerbos PDP

If an existing Cerbos PDP fleet is already running, Synapse can be deployed as a gateway in front of it instead of running an embedded PDP. Replace the pdp.inProcess block with pdp.external and point it at the PDP’s gRPC endpoint:

server:
  listenAddress: ":3594"

pdp:
  external:
    grpcAddress: cerbos-pdp:3593 (1)
    httpAddress: cerbos-pdp:3592 (2)
1 gRPC endpoint of the upstream Cerbos PDP. Synapse forwards authorization traffic to this address.
2 HTTP endpoint of the upstream Cerbos PDP. Used for admin and health-check traffic.

Extensions behave the same in either mode. A proxy extension that enriches the principal runs before the request is forwarded to the external PDP; no extension code changes.

Using Synapse with Docker Compose

The following compose.yaml runs Synapse alongside an application container on the same Docker network. The application can reach Synapse at http://synapse:3594:

services:
  synapse:
    image: CERBOS_DISTRIBUTION_REPO/synapse/synapse:latest
    command:
      - server
      - "--conf.path=/config/config.yaml"
    ports:
      - "3594:3594"
    volumes:
      - ./config.yaml:/config/config.yaml:ro
      - ./policies:/policies:ro
      - ./extensions:/extensions:ro

  app:
    image: your-app:latest
    environment:
      CERBOS_URL: "http://synapse:3594"
    depends_on:
      - synapse

The same three bind mounts — configuration, policies and extensions — apply under Compose. For deployments with multiple Synapse instances or shared upstream services (for example, an external Cerbos PDP running in its own container), define each service under the top-level services key and rely on Docker’s default network for service-to-service name resolution.