Docs
GitHubDiscord

Environment variables

Configure URLs, Solana, tenancy, and optional services for a self-hosted instance.

Local Docker Compose works without an environment file. To change the defaults, copy .env.example. For a public instance, start with .env.production.example.

Core settings

  • DASHBOARD_URL: Public dashboard URL. Required in production. Local Docker derives it from DASHBOARD_PORT when omitted.
  • DASHBOARD_PORT: Host port used by the Docker dashboard.
  • API_PORT: Port used by the API. Docker Compose sets this by default.
  • MONGODB_URI: MongoDB connection string. Leave empty to use the MongoDB container included with Compose.
  • APP_SECRET: Signs sessions and encrypts stored values. Set it in production and keep the same value across restarts and replicas.
  • ZONELESS_TELEMETRY: Set to 0 to disable anonymous usage reporting. Reporting is off by default unless enabled during setup.

Solana

  • LIVEMODE: Set to false for Solana devnet or true for mainnet.
  • SOLANA_RPC_URL: Solana RPC endpoint. When omitted, Zoneless uses the public endpoint for the selected network. Use a dedicated RPC provider in production.
  • SUBSCRIPTION_OPERATOR_KEY: Base58 secret key that owns on-chain subscription plans. Required for recurring prices.
  • TRANSACTION_FEE_PAYER_KEY: Optional Base58 key used to pay Checkout network fees and rent. When omitted, the customer pays through their wallet.
  • CHECKOUT_URL: Optional Checkout origin, such as https://checkout.yourdomain.com. When omitted, Checkout uses DASHBOARD_URL/c/:id.
  • PAYMENT_LINK_URL: Optional Payment Links origin. When omitted, Zoneless uses CHECKOUT_URL or DASHBOARD_URL/b/:id.

Tenancy and operator mode

  • SINGLE_TENANT: Defaults to true. Set to false to allow more than one account on the instance.
  • OPERATOR_API_KEY: Enables operator mode. This disables public setup and provisions accounts through /v1/operator. Operator mode ignores SINGLE_TENANT. Generate the key with openssl rand -hex 32.

Subscription billing

Self-hosted recurring billing needs a scheduled job. Use the HTTP billing endpoint in production.

  • POST /v1/billing/run_for_platform: Call on a schedule with your API key. See Billing Helpers.
  • BILLING_MONITOR_ENABLED: Enables the built-in poller. Use only for local or single-instance deployments.
  • BILLING_POLL_INTERVAL_MS: Poll interval in milliseconds. Defaults to 60000.
Local configuration
cp .env.example .env
Production essentials
DASHBOARD_URL=https://dashboard.yourdomain.com
APP_SECRET=your_generated_secret
LIVEMODE=true
SINGLE_TENANT=true

Next steps