Services
Running a Private Channels instance means owning the following Docker Compose services:
| Container | Role |
|---|---|
private-channel-postgres-primary | Write node state database (PostgreSQL 16) |
private-channel-postgres-replica | Read node state database (streaming replica) |
private-channel-postgres-indexer | Indexer and operator database |
private-channel-write-node | Receives and executes transactions (port 8900, loopback-only) |
private-channel-read-node | Handles RPC read queries (port 8901, loopback-only) |
private-channel-gateway | Routes requests between write and read nodes; enforces RBAC (port 8899) |
private-channel-indexer-solana | Watches Solana for Deposit events via Yellowstone gRPC |
private-channel-indexer-private-channel | Watches the channel for Burn events via RPC polling |
private-channel-operator-solana | Mints channel tokens when deposits are confirmed |
private-channel-operator-private-channel | Calls ReleaseFunds on Mainnet when withdrawals are confirmed |
private-channel-auth | Optional JWT/RBAC service (Docker profile: auth) |
Observability containers (prometheus, grafana, cadvisor) are also
included.
Gateway
These have sensible defaults for the devnet Docker Compose setup. Override only if running the gateway outside Docker or deploying to production.
| Env Var | Default | Required | Description |
|---|---|---|---|
GATEWAY_PORT | 8899 (devnet) | No | Listen port |
GATEWAY_WRITE_URL | http://write-node:8900 (devnet env file value; no binary default) | Yes | Write node URL - sendTransaction routes here |
GATEWAY_READ_URL | http://read-node:8901 (devnet env file value; no binary default) | Yes | Read node URL - all other RPC methods route here |
GATEWAY_CORS_ALLOWED_ORIGIN | * | No | Access-Control-Allow-Origin header value |
JWT_SECRET | - | No | Enables RBAC; must match auth service JWT_SECRET |
AUTH_DATABASE_URL | - | If JWT_SECRET set | Auth DB for wallet ownership checks |
AUTH_DATABASE_MAX_CONNECTIONS | 10 | No | Auth DB connection pool size |
METRICS_PORT | 9101 | No | Prometheus metrics port |
RUST_LOG | info | No | Log level |
GATEWAY_WRITE_URLandGATEWAY_READ_URLuse Docker Compose service hostnames (write-node,read-node) when running in Docker. Uselocalhostequivalents only when running the gateway binary directly outside Docker.The gateway binary's own built-in default for
GATEWAY_PORTis8898..env.exampleand.env.devnetboth set it to8899, which is what the Docker Compose setup actually uses (versions.envholds only toolchain and image version pins, not service ports). The8898default only applies if you run the binary directly with no env file.
GATEWAY_CORS_ALLOWED_ORIGIN defaults to *, which allows any origin to call
the gateway from a browser. Restrict this to your application's actual origin
before any production deployment.
Write Node and Read Node
The full write node and read node configuration reference is in
docs/CONFIG.md
in the repository.
Auth Service
| Env Var | Required | Description |
|---|---|---|
JWT_SECRET | Yes | HS256 signing secret; must match the gateway's JWT_SECRET |
AUTH_PORT | No (default 8903) | Listen port |
AUTH_DATABASE_URL | Yes | PostgreSQL connection string for the auth database |
CORS_ALLOWED_ORIGIN | No (default *) | Access-Control-Allow-Origin header value for this service (independent of the gateway's own GATEWAY_CORS_ALLOWED_ORIGIN) |
AUTH_DATABASE_MAX_CONNECTIONS | No (default 10) | Auth DB connection pool size |
Service Port Reference
| Service | Host Port | Binding |
|---|---|---|
| Gateway | 8899 | All interfaces |
| Write node | 8900 | Loopback only |
| Read node | 8901 | Loopback only |
| Streamer | 8902 | Internal only (expose, not published to the host); not part of the devnet stack |
| Auth service | 8903 | All interfaces |
| Operator metrics | 9102, 9103 | All interfaces |
| Grafana | 37429 | All interfaces |
| Prometheus | 9090 | All interfaces |
| cAdvisor | 8080 | All interfaces |
Security note: Write-node and read-node ports are bound to loopback (
127.0.0.1) only. Gateway, Auth service, operator metrics, Grafana, Prometheus, and cAdvisor are all published to every network interface in the devnet Docker Compose setup. Firewall these at the host or network level for anything beyond local development; RBAC only covers the gateway's own JSON-RPC methods, not these other services. The Streamer is the exception: it is an unauthenticated internal feed that Docker never publishes to the host.
Network Requirements
See
docs/TECHNICAL_REQUIREMENTS.md
in the repository for firewall rules and bandwidth requirements.
Is this page helpful?