> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varianz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Running the coordinator locally

> Run the Varianz coordinator in Docker for local development and CI: image, ports, plaintext vs TLS, and Postgres-backed persistence.

The coordinator ships as a Docker image. Unlike the SDK packages on `pkgs.varianz.io`, the image is pulled from Google Artifact Registry and **does** need credentials — your team's access is set up during onboarding ([details](/installation#getting-the-coordinator-image)).

## Local development (in-memory, plaintext)

```bash theme={null}
docker run --rm -p 50051:50051 \
  -e COORDINATOR_INSECURE_PLAINTEXT=true \
  us-docker.pkg.dev/varianz-dist/coordinator-slim/coordinator-server:v0.2.1
```

* Listens on gRPC port **50051** (dual-stack). It logs `LocalCoordinator listening on http://[::]:50051 (dual-stack)` when ready.
* State is **in-memory** — sessions, stages, and registrations reset on restart. That's usually what you want for dev and CI.
* `COORDINATOR_INSECURE_PLAINTEXT=true` (or the `--insecure-plaintext` flag) lets the server accept plaintext connections. The server is TLS-required by default and refuses to start without either TLS material or this flag.

Clients connecting to a plaintext coordinator need `VARIANZ_INSECURE_ALLOW_PLAINTEXT=true` in their environment — [both sides must agree](/reference/configuration#tls).

Docker tags are `v`-prefixed (`v0.2.1`), unlike the package-manager versions (`0.2.1`).

## Flags and environment

| Flag                                              | Env                              | Purpose                                                   |
| ------------------------------------------------- | -------------------------------- | --------------------------------------------------------- |
| `--port`, `-p`                                    | `COORDINATOR_PORT`               | Listen port (default 50051; `--port 0` picks a free port) |
| `--insecure-plaintext`                            | `COORDINATOR_INSECURE_PLAINTEXT` | Accept plaintext connections                              |
| `--tls-cert` / `--tls-key` / `--tls-key-password` | `COORDINATOR_TLS_*`              | Serve TLS from PEM material                               |
| `--tls-keystore` / `--tls-keystore-password`      | `COORDINATOR_TLS_*`              | Serve TLS from a PKCS#12 keystore                         |
| `--config`                                        | `COORDINATOR_CONFIG`             | TOML config file                                          |
| `--postgres-url`                                  | `COORDINATOR_PG_URL`             | Durable backend: Postgres with a write-behind cache       |
| `--uncached` (with `--postgres-url`)              | `COORDINATOR_PG_UNCACHED`        | Postgres-direct, no cache layer                           |

Flags and environment variables override the config file.

## TLS for shared environments

For anything beyond a laptop — a shared dev cluster, CI infrastructure others connect to — run the coordinator with TLS:

```bash theme={null}
docker run --rm -p 50051:50051 \
  -v /path/to/certs:/certs:ro \
  us-docker.pkg.dev/varianz-dist/coordinator-slim/coordinator-server:v0.2.1 \
  --port 50051 --tls-cert /certs/server.pem --tls-key /certs/server-key.pem
```

Clients then need no plaintext override; if the CA isn't in the platform trust store, point them at it with `VARIANZ_TLS_CA` ([client TLS settings](/reference/configuration#tls)).

## CI tips

* Bind `--port 0` and parse the logged port to avoid collisions between parallel jobs, or give each job its own container network.
* Start the coordinator **before** the services under test: services register their VPoints at startup (fail-open with a \~5s timeout, so a late coordinator means lazily-degraded VPoints rather than crashes — but tests will then see [zero subscribers](/testing/overview#zero-subscribers)).
* Tests that only exercise behavior inside a single process don't need a coordinator at all — see [local stages](/concepts/stages#local-stages).