Running the registry locally

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)

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. 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:

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).

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).

Getting started

Core concepts

Guides

SDK reference

Testing

Reference

Running the registry locally

Local development (in-memory, plaintext)

Flags and environment

TLS for shared environments

CI tips

​Local development (in-memory, plaintext)

​Flags and environment

​TLS for shared environments

​CI tips

Local development (in-memory, plaintext)

Flags and environment

TLS for shared environments

CI tips