# 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](https://docs.cerbos.dev/synapse/latest/install/helm) instead.

The [Quick Start](https://docs.cerbos.dev/synapse/latest/quickstart) 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](/content/workshop/index.html). 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:

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

Pull the image:

```console
$ 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`:

```console
$ 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:

```console
$ 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](https://docs.cerbos.dev/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](https://docs.cerbos.dev/synapse/latest/configuration/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](https://docs.cerbos.dev/synapse/latest/quickstart) uses this approach. It is not suitable for production.

```yaml
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:

```console
$ 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](https://docs.cerbos.dev/synapse/latest/configuration/reference) for the Synapse-specific configuration schema, and the [Cerbos PDP configuration documentation](https://docs.cerbos.dev/cerbos/latest/configuration/) 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:

```yaml
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`:

```yaml
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.