Provider

This page is auto-synced from apps/provider/README.md in the pokt-network/igniter repo. Edit it there — changes here are overwritten on every build.

The Provider app is the operator-facing web interface for Pocket Network supplier operations (Shannon protocol). It provides tooling to help operators manage supplier keys, configure stakes, organize address groups, and set up delegator revenue sharing.

This README covers configuration and usage for node operators. For local development with Tilt, see the Contributing guide.

Deployment
Environment Variables
Database Migrations
Bootstrap Wizard
Guides
Reference

Deployment

For step-by-step deployment instructions (dependencies, configuration, and startup), see the Docker Compose guide.

Provider serves an admin portal and a small machine API on the same port. Only the API needs to be public — see Exposing the Provider API for the exact path allowlist, a default-deny nginx configuration, and how to keep the portal reachable for yourself.

Environment Variables

Provider reads its configuration from a single .env file at docker-compose/apps/provider/.env. Copy .env.sample as a starting point.

All variables below are sourced from docker-compose/apps/provider/.env.sample.

Compose

Variable	Required	Description	Example / Default
`COMPOSE_PROJECT_NAME`	Optional	Docker Compose project name — scopes container names	`igniter-provider`

Next.js

Variable	Required	Description	Example / Default
`NODE_ENV`	Optional	Node runtime environment	`production`
`LOG_LEVEL`	Optional	LogTape verbosity (`trace`, `debug`, `info`, `warning`, `error`, `fatal` — note `warning`, not `warn`)	`debug`

Temporal

Variable	Required	Description	Example / Default
`TEMPORAL_URL`	Required	Address of the Temporal server (from dependencies compose)	`temporal:7233`
`TEMPORAL_NAMESPACE`	Required	Temporal namespace for Provider workflows	`provider`
`TEMPORAL_TASK_QUEUE`	Required	Task queue name for dispatching workflow tasks	`provider-operations`
`TEMPORAL_WORKFLOW_RETENTION`	Optional	How long to retain completed workflow history, in seconds	`604800` (7 days)

PostgreSQL

Variable	Required	Description	Example / Default
`PGHOST`	Required	PostgreSQL hostname (service name from dependencies compose)	`postgresql`
`PGUSER`	Required	PostgreSQL username — must match `POSTGRES_USER` in dependencies `.env`	`igniter`
`PGPASSWORD`	Required	PostgreSQL password — must match `POSTGRES_PASSWORD` in dependencies `.env`	(no default — set this)
`DB_NAME`	Required	Database name for Provider	`provider`
`DATABASE_URL`	Required	Full connection string — interpolated from the four vars above	`postgres://${PGUSER}:${PGPASSWORD}@${PGHOST}:5432/${DB_NAME}?sslmode=disable`

Note: PGPASSWORD must exactly match POSTGRES_PASSWORD in docker-compose/dependencies/.env. If they don’t match, migrations and the app will fail to connect.

Pocket Network

Variable	Required	Description	Example / Default
`POKT_RPC_URL`	Required	CometBFT RPC endpoint. Seeded into the database on first boot if not already configured via the setup wizard	`https://sauron-rpc.beta.infra.pocket.network`
`CHAIN_ID`	Required	Blockchain chain identifier	`pocket-beta`
`BLOCKCHAIN_PROTOCOL`	Required	Protocol version (`shannon`)	`shannon`
`OWNER_IDENTITY`	Required	POKT bech32 wallet address of the Provider owner — must be a valid `pokt1...` address. Used to restrict pre-bootstrap login via SIWP	`pokt1abc123...`
`OWNER_EMAIL`	Required	Email address for the owner account	`operator@example.com`
`APP_IDENTITY`	Required	Hex-encoded private key that establishes the Provider’s identity. Its public key is what you register in the governance registry and what `/api/identity` serves. Use a dedicated key that holds no funds — see the note below	`openssl rand -hex 32`
`MINIMUM_STAKE_BUFFER`	Optional	Buffer subtracted from minimum on-chain stake to allow nodes to operate after slashes, in uPOKT	`500000000`
`DELEGATORS_CDN_URL`	Optional	CDN URL template for fetching delegator configuration JSON. `{chainId}` is replaced at runtime	`https://raw.githubusercontent.com/.../middleman.json`

APP_IDENTITY must be a dedicated key that holds no funds. Generate a fresh one with openssl rand -hex 32; never reuse the private key of a wallet you hold POKT in, and never send funds to the address it derives.

Three reasons. It is stored as plaintext in the container environment — unlike supplier keys, which are encrypted at rest with ENCRYPTION_KEY, so anyone who reads the environment or the .env file holds the key outright. Its public key is published in the governance registry, so the address derived from it is public and permanently linked to your instance. And it is a real secp256k1 private key: the Provider only derives a public key from it today and never signs with it, but signPayload() in @igniter/commons signs as sha256(utf8(payload)) — the same construction Cosmos uses for amino-JSON transactions — so if the Provider ever gains a signing path, a funded key becomes a drainable one.

Application

Variable	Required	Description	Example / Default
`APP_URL`	Required	Public URL where Provider is accessible — used for redirect links and CORS	`http://localhost:3001`
`AUTH_URL`	Required	URL used by NextAuth for auth callbacks — typically same as `APP_URL`	`http://localhost:3001`
`AUTH_TRUST_HOST`	Optional	Set `true` if running behind a reverse proxy (trusts `X-Forwarded-*` headers)	`false`

Security / Encryption

Variable	Required	Description	How to generate
`ENCRYPTION_IV`	Required	Initialization vector for database private key encryption	`openssl rand -hex 16`
`ENCRYPTION_KEY`	Required	Key for database private key encryption	`openssl rand -hex 32`
`AUTH_SECRET`	Required	Secret used to encrypt website session tokens	`openssl rand -hex 24`

Note: Generate unique values for ENCRYPTION_IV, ENCRYPTION_KEY, and AUTH_SECRET before deploying. Never reuse values across environments or share them publicly.

Database Migrations

Migrations run automatically via the provider-migration service every time you run docker compose up. The service uses Drizzle ORM to apply any pending schema changes, then exits with code 0. The web and workflows services will not start until migration completes successfully.

If you need to run migrations manually outside of Docker (e.g., in CI or during local development):

bash

pnpm provider:migration:migrate

Bootstrap Wizard

After deployment, the Provider app is running but not yet configured. The bootstrap wizard is a one-time setup flow that walks you through connecting to the blockchain, setting your identity, configuring regions, relay miners, services, address groups, and delegators.

For the detailed step-by-step walkthrough, see the Bootstrap guide.

Guides

Step-by-step tutorials for common Provider workflows.

Guide	What it covers
Bootstrap Wizard	One-time setup wizard — blockchain, identity, regions, miners, services
How to set up a relay miner with address groups	Configure a miner, create groups, and assign services step by step
How to manage your key inventory	Import keys, track their lifecycle states, and export when needed
How to onboard a new delegator	End-to-end flow from receiving keys to enabling a delegator
Notifications	Set up Discord, Telegram, or email delivery for supplier and workflow events
Exposing the Provider API	Publish only the API paths Middleman and governance need; keep the admin portal private

Reference

Detailed feature documentation for each admin area.

Doc	What it covers
Relay Miners	Register and configure relay miner nodes
Address Groups	Organize miners into groups with service and revenue share configuration
Key Management	Import, track, and export supplier keys through their lifecycle
Delegators	Enable delegators and manage revenue sharing, including CDN import
Workflows	Inspect running/recent Temporal workflows and schedule health
Notifications	Instance-wide event types, channels, shared SMTP, and delivery config