Deployment

Qustody is distributed as a single Go binary plus a PostgreSQL database. Most production deployments run it as a container behind a load balancer, with managed Postgres (AWS RDS, Aurora, or equivalent) and a separate signing service.

Prerequisites

Go 1.24+ if you build from source
PostgreSQL 16+ (the schema is auto-migrated on startup when CUSTODY_DB_MIGRATE_ON_START=true)
A reachable Quantum Chain RPC node (HTTP and optionally WebSocket)
An external post-quantum signing service (callback HTTP, remote HTTP, or gRPC)
TLS certificates for production (terminated at your load balancer or directly on the API)

Container image

A multi-stage Dockerfile is shipped at custody/Dockerfile:

# Build
docker build -t qustody-api:latest -f custody/Dockerfile .

# Run
docker run --rm -p 8080:8080 -p 9090:9090 \
  -e CUSTODY_DB_HOST=postgres \
  -e CUSTODY_DB_PASSWORD=secret \
  -e CUSTODY_NODE_RPC_URL=http://quantum-chain:8545 \
  -e CUSTODY_AUTH_ENABLED=true \
  qustody-api:latest

The container exposes:

8080 — HTTP API
9090 — Prometheus metrics (/metrics)

Local development with Docker Compose

A reference docker-compose.yaml lives at the repo root and brings up PostgreSQL, the Qustody API, and a development Quantum Chain node:

docker compose up -d postgres api
docker compose logs -f api

The development profile uses CUSTODY_AUTH_ENABLED=false and CUSTODY_RBAC_ENABLED=false to make exploration easy. Never deploy that combination.

Production deployment

Recommended topology

Run at least two replicas behind a load balancer. The API is stateless; replicas coordinate through PostgreSQL row-level locks for transaction recovery.

Required environment variables

Variable	Description
`CUSTODY_DB_HOST`, `CUSTODY_DB_PORT`, `CUSTODY_DB_NAME`, `CUSTODY_DB_USER`, `CUSTODY_DB_PASSWORD`	PostgreSQL connection
`CUSTODY_DB_SSLMODE`	Set to `verify-full` in production
`CUSTODY_NODE_RPC_URL`	Quantum Chain HTTP RPC endpoint
`CUSTODY_NODE_WS_URL`	Quantum Chain WebSocket endpoint (for deposit monitoring)
`CUSTODY_AUTH_ENABLED`	`true`
`CUSTODY_RBAC_ENABLED`	`true`
`CUSTODY_WEBHOOK_SIGNING_KEY`	Random 32-byte hex string
`CUSTODY_WEBHOOK_ENCRYPTION_KEY`	64-hex-char (32 byte) AES-256-GCM key for webhook secret encryption at rest
`CUSTODY_ENV`	`production` (enforces HTTPS for tenant and webhook URLs)

See the full list at Configuration reference.

Aurora / read-replica configuration

CUSTODY_DB_HOST=writer.cluster-xxx.us-east-1.rds.amazonaws.com
CUSTODY_DB_READ_REPLICA_ENABLED=true
CUSTODY_DB_READ_HOST=reader.cluster-ro-xxx.us-east-1.rds.amazonaws.com
CUSTODY_DB_IAM_AUTH=true
CUSTODY_DB_SSL_ROOT_CERT=/etc/ssl/rds-ca.pem

When CUSTODY_DB_IAM_AUTH=true, CUSTODY_DB_PASSWORD is not required — Qustody uses RDS IAM tokens.

Signer configuration (gRPC mode)

CUSTODY_SIGNER_TYPE=grpc
CUSTODY_SIGNER_BACKEND=enqlave    # or "qey"
CUSTODY_SIGNER_GRPC_TARGET=signer.internal:443
CUSTODY_SIGNER_GRPC_CLIENT_CERT=/etc/qustody/client.crt
CUSTODY_SIGNER_GRPC_CLIENT_KEY=/etc/qustody/client.key
CUSTODY_SIGNER_GRPC_CA_CERT=/etc/qustody/ca.crt
CUSTODY_SIGNER_GRPC_TIMEOUT=30s

For callback or remote modes see External signing.

SSO

CUSTODY_SSO_ENABLED=true
CUSTODY_SSO_JWT_SIGNING_KEY=<32 random bytes hex-encoded>
CUSTODY_SSO_ALLOWED_ISSUERS=https://login.example.com,https://accounts.google.com
CUSTODY_SSO_AUTO_PROVISION=true
CUSTODY_SSO_DEFAULT_ROLE=viewer

Compliance / AML

CUSTODY_COMPLIANCE_ENABLED=true
CUSTODY_COMPLIANCE_PROVIDER=shuftipro     # or "chainalysis", "noop"
CUSTODY_SHUFTIPRO_CLIENT_ID=...
CUSTODY_SHUFTIPRO_SECRET_KEY=...
CUSTODY_SHUFTIPRO_CALLBACK_URL=https://api.your-domain.com/v1/compliance/callback/shuftipro

Health and readiness

The API exposes two endpoints used by load balancers and orchestrators:

Endpoint	Purpose
`GET /healthz`	Liveness — returns `200 OK` if the process is alive
`GET /readyz`	Readiness — returns `200 OK` only when DB and signer are reachable

In Kubernetes:

livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
  periodSeconds: 10
readinessProbe:
  httpGet: { path: /readyz, port: 8080 }
  periodSeconds: 5

Observability

Surface	Endpoint / sink
Metrics	`:9090/metrics` (Prometheus format)
Tracing	OpenTelemetry OTLP when `CUSTODY_OTEL_ENABLED=true` and `CUSTODY_OTEL_ENDPOINT` is set
Logs	Structured JSON to stdout
Health	`GET /healthz`, `GET /readyz`

Enable rate limiting with Redis for distributed deployments:

CUSTODY_RATE_LIMIT_ENABLED=true
CUSTODY_RATE_LIMIT_RPM=120
CUSTODY_RATE_LIMIT_BURST=20
CUSTODY_RATE_LIMIT_REDIS_URL=redis://redis:6379/0

Database migrations

Migrations live in custody/store/postgres/migrations/. They are applied automatically on startup when CUSTODY_DB_MIGRATE_ON_START=true (default). For zero-downtime upgrades, run migrations from a single instance with CUSTODY_DB_MIGRATE_ON_START=true and start the rest with false.

Backups and disaster recovery

PostgreSQL is the source of truth. Use point-in-time recovery (PITR).
Audit log integrity is verifiable independently via GET /v1/audit/verify.
Webhook secrets are encrypted column-level when CUSTODY_WEBHOOK_ENCRYPTION_KEY is set; back up the key separately.

Getting started

Concepts

Qustody platform

Token management

Reference

Development

Prerequisites

Container image

Local development with Docker Compose

Production deployment

Recommended topology

Required environment variables

Aurora / read-replica configuration

Signer configuration (gRPC mode)

SSO

Compliance / AML

Health and readiness

Observability

Database migrations

Backups and disaster recovery

​Prerequisites

​Container image

​Local development with Docker Compose

​Production deployment

​Recommended topology

​Required environment variables

​Aurora / read-replica configuration

​Signer configuration (gRPC mode)

​SSO

​Compliance / AML

​Health and readiness

​Observability

​Database migrations

​Backups and disaster recovery

​Related

Prerequisites

Container image

Local development with Docker Compose

Production deployment

Recommended topology

Required environment variables

Aurora / read-replica configuration

Signer configuration (gRPC mode)

SSO

Compliance / AML

Health and readiness

Observability

Database migrations

Backups and disaster recovery

Related