> ## 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 registry locally

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

The registry server ships as a Docker image; image access is set up for your team during onboarding. The SDK packages on `pkgs.varianz.io` need no credentials — only the container image does.

## Local development (in-memory, plaintext)

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

* Listens on gRPC port **50051** (dual-stack). It logs `LocalRegistry listening on http://[::]:50051` when ready.
* State is **in-memory** — sessions, stages, and registrations reset on restart. That's usually what you want for dev and CI.
* `REGISTRY_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 registry 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`                                    | `REGISTRY_PORT`               | Listen port (default 50051; `--port 0` picks a free port) |
| `--insecure-plaintext`                            | `REGISTRY_INSECURE_PLAINTEXT` | Accept plaintext connections                              |
| `--tls-cert` / `--tls-key` / `--tls-key-password` | `REGISTRY_TLS_*`              | Serve TLS from PEM material                               |
| `--tls-keystore` / `--tls-keystore-password`      | `REGISTRY_TLS_*`              | Serve TLS from a PKCS#12 keystore                         |
| `--config`                                        | `REGISTRY_CONFIG`             | TOML config file                                          |
| `--postgres-url`                                  | `REGISTRY_PG_URL`             | Durable backend: Postgres with a write-behind cache       |
| `--uncached` (with `--postgres-url`)              | `REGISTRY_PG_UNCACHED`        | Postgres-direct, no cache layer                           |

## TLS for shared environments

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

```bash theme={null}
docker run --rm -p 50051:50051 \
  -v /path/to/certs:/certs:ro \
  us-docker.pkg.dev/varianz-dist/registry/registry-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 registry **before** the services under test: services register their VPoints at startup (fail-open with a \~5s timeout, so a late registry means lazily-degraded VPoints rather than crashes — but tests will then see [zero subscribers](/testing/overview#zero-subscribers)).