Environment Variables

AxiomDB components are configured through environment variables. This reference covers every supported variable across the console, gateway, database host, IdP integration, provisioning, and resilience layers.

Console

Variables that control the AxiomDB console (Next.js frontend) and documentation site.

NODE_ENV

The Node.js runtime environment. Affects logging verbosity, error detail, and build optimizations.

NODE_ENV=production

Default: development

PORT

The port the console server listens on.

PORT=3000

Default: 3000

HOSTNAME

The hostname the console binds to. Use 0.0.0.0 to listen on all interfaces, or 127.0.0.1 for localhost-only access.

HOSTNAME=0.0.0.0

Default: localhost

ASTRADB_PUBLIC_URL

The public-facing URL of the AxiomDB console. Used for generating links in emails, OAuth callbacks, and API documentation.

ASTRADB_PUBLIC_URL=https://console.axiomdb.io

Default: http://localhost:3000

Required in production.

AXIOMDB_DOCS_DOMAIN

The domain hosting the AxiomDB documentation site. Used for cross-origin linking and sitemap generation.

AXIOMDB_DOCS_DOMAIN=docs.axiomdb.io

Default: docs.axiomdb.io

NEXT_PUBLIC_AXIOMDB_DOCS_URL

The full URL of the documentation site, exposed to the browser (Next.js public runtime variable).

NEXT_PUBLIC_AXIOMDB_DOCS_URL=https://docs.axiomdb.io

Default: https://docs.axiomdb.io

Gateway Auth

Variables controlling authentication flows between the console and Square IdP.

ASTRADB_AUTH_MODE

The authentication mode for the gateway. Determines how sessions are validated and tokens are issued.

ASTRADB_AUTH_MODE=oidc

Default: oidc

OPS_CONSOLE_SESSION_SECRET

A cryptographically random secret used to sign console session cookies. Must be at least 32 bytes.

OPS_CONSOLE_SESSION_SECRET=$(openssl rand -base64 48)

Required. No default.

SQUARE_AUTH_BASE_URL

The base URL of the Square authentication service.

SQUARE_AUTH_BASE_URL=https://auth.square.com

Default: https://auth.square.com

SQUARE_AUTH_LOGIN_PATH

The URL path for the login endpoint on the Square auth service.

SQUARE_AUTH_LOGIN_PATH=/oauth/authorize

Default: /oauth/authorize

SQUARE_AUTH_SIGNUP_PATH

The URL path for new user registration on the Square auth service.

SQUARE_AUTH_SIGNUP_PATH=/signup

Default: /signup

SQUARE_AUTH_VERIFY_PATH

The URL path for token verification / introspection.

SQUARE_AUTH_VERIFY_PATH=/oauth/tokeninfo

Default: /oauth/tokeninfo

SQUARE_AUTH_TIMEOUT_MS

Timeout in milliseconds for requests to the Square auth service. If exceeded, the request fails with a gateway timeout.

SQUARE_AUTH_TIMEOUT_MS=10000

Default: 5000 (5 seconds)

Database Host

Variables for the PostgreSQL database host that serves AxiomDB project databases.

DB_PUBLIC_HOST

The publicly resolvable hostname for database connections. This is the hostname returned in connection strings to users.

DB_PUBLIC_HOST=us-east-1.aws.axiomdb.io

Required in production.

POSTGRES_HOST

The internal hostname or IP address of the PostgreSQL server. Used by the gateway to establish backend connections.

POSTGRES_HOST=10.0.1.50

Default: localhost

POSTGRES_PORT

The port the PostgreSQL server listens on.

POSTGRES_PORT=5432

Default: 5432

App Connection Strings

Variables used by applications to connect to AxiomDB databases.

DATABASE_URL

The primary connection string for the application. Includes connection pooling (PgBouncer in transaction mode).

DATABASE_URL="postgresql://user:password@ep-main-abc123.us-east-1.aws.axiomdb.io:5432/axiomdb?sslmode=require"

Format:

postgresql://<user>:<password>@<host>:<port>/<database>?sslmode=require

Used by:

• Prisma (datasource.db.url)
• Drizzle (postgres())
• TypeORM (type: "postgres")
• pg / node-postgres (new Pool({ connectionString }))
• Any PostgreSQL client library

DIRECT_URL

A direct (non-pooled) connection to the database. Bypasses the connection pooler and creates a persistent session-level connection.

DIRECT_URL="postgresql://user:password@ep-main-abc123-session.us-east-1.aws.axiomdb.io:5432/axiomdb?sslmode=require"

Used for:

• Prisma migrations (datasource.db.directUrl)
• Schema introspection
• Long-running transactions
• LISTEN/NOTIFY channels
• Advisory locks

Gateway

Variables for the AxiomDB control plane gateway — the service that manages project provisioning, routing, and API access.

DATABASE_URL (Control Plane)

The connection string for the gateway's own control plane database. This is a separate database from user project databases.

DATABASE_URL="postgresql://gateway:secret@localhost:5432/axiomdb_control"

Required for the gateway service.

REDIS_URL

The connection URL for the Redis instance used by the gateway for caching, session storage, and rate limiting.

REDIS_URL="redis://default:password@redis.axiomdb.io:6379/0"

Format:

redis://<username>:<password>@<host>:<port>/<db>

Default: redis://localhost:6379/0

Used for:

• Session cache
• Rate limit counters
• Connection pool metadata cache
• Pub/Sub for real-time monitoring streams
• Temporary token storage

BIND_ADDR

The address and port the gateway server binds to.

BIND_ADDR=0.0.0.0:8080

Default: 0.0.0.0:8080

JWT_SECRET

The HMAC-SHA256 secret used to sign and verify JWT access and refresh tokens issued by the gateway.

JWT_SECRET=$(openssl rand -base64 64)

Required. No default.

JWT_ACCESS_TTL_SECS

The time-to-live in seconds for JWT access tokens. After expiration, clients must use a refresh token to obtain a new access token.

JWT_ACCESS_TTL_SECS=900

Default: 900 (15 minutes)

Recommended range: 300–3600 (5 minutes to 1 hour)

JWT_REFRESH_TTL_SECS

The time-to-live in seconds for JWT refresh tokens. After expiration, users must re-authenticate.

JWT_REFRESH_TTL_SECS=604800

Default: 604800 (7 days)

Recommended range: 86400–2592000 (1–30 days)

Identity Provider (IdP)

Variables for integrating with Square IdP via OpenID Connect (OIDC) and OAuth 2.0.

BASE_IDP_PUBLIC_KEY_BASE64

The base64-encoded RSA public key used to verify JWT tokens issued by Square IdP. This is the IdP's token signing key.

BASE_IDP_PUBLIC_KEY_BASE64="MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."

Alternative: If BASE_IDP_KEY_ENDPOINT is set, the public key is fetched dynamically and this variable is optional.

BASE_IDP_KEY_ENDPOINT

The URL of the IdP's JWKS (JSON Web Key Set) endpoint. Used to dynamically fetch and cache the public key for token verification.

BASE_IDP_KEY_ENDPOINT=https://auth.square.com/.well-known/jwks.json

Default: https://auth.square.com/.well-known/jwks.json

BASE_IDP_ISSUER

The iss (issuer) claim expected in tokens from the IdP. Tokens with a different issuer are rejected.

BASE_IDP_ISSUER=https://auth.square.com

Default: https://auth.square.com

BASE_IDP_AUDIENCE

The aud (audience) claim expected in tokens. Tokens intended for a different audience are rejected.

BASE_IDP_AUDIENCE=axiomdb-gateway

Required. No default.

BASE_IDP_TOKEN_ENDPOINT

The IdP's token endpoint for exchanging authorization codes for tokens (OAuth 2.0 token exchange).

BASE_IDP_TOKEN_ENDPOINT=https://auth.square.com/oauth/token

Default: https://auth.square.com/oauth/token

BASE_IDP_AUTHORIZE_ENDPOINT

The IdP's authorization endpoint for initiating the OAuth 2.0 authorization code flow.

BASE_IDP_AUTHORIZE_ENDPOINT=https://auth.square.com/oauth/authorize

Default: https://auth.square.com/oauth/authorize

BASE_IDP_CLIENT_ID

The OAuth 2.0 client ID for the AxiomDB console (server-side web application).

BASE_IDP_CLIENT_ID=axiomdb-console-prod

Required. No default.

BASE_IDP_CLIENT_SECRET

The OAuth 2.0 client secret for the AxiomDB console. Used in the authorization code exchange.

BASE_IDP_CLIENT_SECRET=secret_xxxxxxxxxxxxxxxxxxxxxxxx

Required. No default.

BASE_IDP_REDIRECT_URI

The OAuth 2.0 redirect URI registered with the IdP. Must match exactly what is configured in the Square IdP client registration.

BASE_IDP_REDIRECT_URI=https://console.axiomdb.io/api/auth/callback

Required. No default.

BASE_IDP_CLI_CLIENT_ID

A separate OAuth 2.0 client ID for the axm CLI tool. The CLI uses a different client than the console to support PKCE-based public client flows.

BASE_IDP_CLI_CLIENT_ID=axiomdb-cli-prod

Required. No default.

BASE_IDP_CLI_SCOPES

Space-separated list of OAuth 2.0 scopes requested by the CLI during authentication.

BASE_IDP_CLI_SCOPES="openid profile email db:read db:write"

Default: openid profile email

BASE_IDP_REQUIRED_SCOPE

The minimum scope a token must contain to be considered valid for AxiomDB API access. Tokens without this scope are rejected with a 403 Forbidden.

BASE_IDP_REQUIRED_SCOPE=axiomdb:access

Required. No default.

Provisioning

Variables for the database provisioning subsystem (dbctl).

DBCTL_BIN

The absolute path to the dbctl binary. This binary handles database creation, branching, snapshotting, and restoration on the database host.

DBCTL_BIN=/usr/local/bin/dbctl

Default: dbctl (resolved from $PATH)

AXIOMDB_SECRET_FILE

Path to a file containing provisioning secrets (database passwords, encryption keys). The file is read at startup and its contents are used for provisioning operations.

AXIOMDB_SECRET_FILE=/etc/axiomdb/secrets.json

File format:

{
  "postgres_superuser_password": "pg_secret_xxxx",
  "encryption_key": "aes256_key_base64_xxxx",
  "backup_encryption_key": "backup_key_base64_xxxx"
}

Default: /etc/axiomdb/secrets.json

Circuit Breaker

Variables that control the circuit breaker pattern implementation for resilient service communication.

CIRCUIT_BREAKER_THRESHOLD

The number of consecutive failures before the circuit breaker trips (opens). While open, all requests fail immediately without contacting the downstream service.

CIRCUIT_BREAKER_THRESHOLD=5

Default: 5

Behavior:

CIRCUIT_BREAKER_TIMEOUT_SECS

The duration in seconds the circuit breaker stays open before transitioning to half-open state. During the half-open state, a single request is allowed through to test if the downstream service has recovered.

CIRCUIT_BREAKER_TIMEOUT_SECS=30

Default: 30 (30 seconds)

Recommended range: 10–120 seconds

Complete Environment File Example

Below is a comprehensive .env file for a production AxiomDB deployment:

# ──────────────────────────────────────────────
# Console
# ──────────────────────────────────────────────
NODE_ENV=production
PORT=3000
HOSTNAME=0.0.0.0
ASTRADB_PUBLIC_URL=https://console.axiomdb.io
AXIOMDB_DOCS_DOMAIN=docs.axiomdb.io
NEXT_PUBLIC_AXIOMDB_DOCS_URL=https://docs.axiomdb.io

# ──────────────────────────────────────────────
# Gateway Auth
# ──────────────────────────────────────────────
ASTRADB_AUTH_MODE=oidc
OPS_CONSOLE_SESSION_SECRET=base64_encoded_secret_here_min_32_bytes
SQUARE_AUTH_BASE_URL=https://auth.square.com
SQUARE_AUTH_LOGIN_PATH=/oauth/authorize
SQUARE_AUTH_SIGNUP_PATH=/signup
SQUARE_AUTH_VERIFY_PATH=/oauth/tokeninfo
SQUARE_AUTH_TIMEOUT_MS=5000

# ──────────────────────────────────────────────
# Database Host
# ──────────────────────────────────────────────
DB_PUBLIC_HOST=us-east-1.aws.axiomdb.io
POSTGRES_HOST=10.0.1.50
POSTGRES_PORT=5432

# ──────────────────────────────────────────────
# App Connection Strings
# ──────────────────────────────────────────────
DATABASE_URL="postgresql://user:pass@ep-main-abc123.us-east-1.aws.axiomdb.io:5432/axiomdb?sslmode=require"
DIRECT_URL="postgresql://user:pass@ep-main-abc123-session.us-east-1.aws.axiomdb.io:5432/axiomdb?sslmode=require"

# ──────────────────────────────────────────────
# Gateway
# ──────────────────────────────────────────────
REDIS_URL=redis://default:password@redis.axiomdb.io:6379/0
BIND_ADDR=0.0.0.0:8080
JWT_SECRET=base64_encoded_jwt_secret_here_min_32_bytes
JWT_ACCESS_TTL_SECS=900
JWT_REFRESH_TTL_SECS=604800

# ──────────────────────────────────────────────
# Identity Provider (Square IdP)
# ──────────────────────────────────────────────
BASE_IDP_KEY_ENDPOINT=https://auth.square.com/.well-known/jwks.json
BASE_IDP_ISSUER=https://auth.square.com
BASE_IDP_AUDIENCE=axiomdb-gateway
BASE_IDP_TOKEN_ENDPOINT=https://auth.square.com/oauth/token
BASE_IDP_AUTHORIZE_ENDPOINT=https://auth.square.com/oauth/authorize
BASE_IDP_CLIENT_ID=axiomdb-console-prod
BASE_IDP_CLIENT_SECRET=secret_xxxxxxxxxxxxxxxxxxxxxxxx
BASE_IDP_REDIRECT_URI=https://console.axiomdb.io/api/auth/callback
BASE_IDP_CLI_CLIENT_ID=axiomdb-cli-prod
BASE_IDP_CLI_SCOPES="openid profile email db:read db:write"
BASE_IDP_REQUIRED_SCOPE=axiomdb:access

# ──────────────────────────────────────────────
# Provisioning
# ──────────────────────────────────────────────
DBCTL_BIN=/usr/local/bin/dbctl
AXIOMDB_SECRET_FILE=/etc/axiomdb/secrets.json

# ──────────────────────────────────────────────
# Circuit Breaker
# ──────────────────────────────────────────────
CIRCUIT_BREAKER_THRESHOLD=5
CIRCUIT_BREAKER_TIMEOUT_SECS=30

Variable Reference Table

A quick-reference table of all environment variables:

Security Best Practices

Secret Generation

Use the axm CLI to generate cryptographically secure values:

# Generate a 32-byte secret
axm secrets generate --label SESSION_SECRET --bytes 32

# Generate a 64-byte JWT secret
axm secrets generate --label JWT_SECRET --bytes 64 --format hex

# Generate with shell integration
export JWT_SECRET=$(axm secrets generate --label JWT_SECRET --bytes 64 --json | jq -r '.value')

Environment Isolation

Use separate .env files per environment:

.env.local          # Local development (gitignored)
.env.staging        # Staging configuration
.env.production     # Production configuration (managed by secrets manager)

Load the correct file based on NODE_ENV:

# Start with production config
NODE_ENV=production node server.js

# Or use a tool like dotenv-cli
npx dotenv -e .env.production -- node server.js

Validation

The AxiomDB gateway validates all required environment variables at startup. Missing or malformed variables produce clear error messages:

✘ Configuration validation failed:
  - JWT_SECRET: required, got undefined
  - BASE_IDP_CLIENT_SECRET: required, got undefined
  - SQUARE_AUTH_TIMEOUT_MS: expected number, got "not-a-number"

  3 errors found. Fix these and restart.