Configuration Reference

Configure Phoenix using environment variables for database, authentication, networking, and more.

Database Configuration

Connection URL

PHOENIX_SQL_DATABASE_URL

string

Complete database connection URL. Supports SQLite and PostgreSQL:

# SQLite (development)
PHOENIX_SQL_DATABASE_URL=sqlite:///phoenix.db

# PostgreSQL (production)
PHOENIX_SQL_DATABASE_URL=postgresql://user:password@host:5432/dbname

PostgreSQL Components

Alternatively, configure PostgreSQL using individual components:

PHOENIX_POSTGRES_HOST

string

PostgreSQL server hostname (e.g., localhost, postgres.example.com, RDS endpoint)

PHOENIX_POSTGRES_PORT

integer

default:"5432"

PostgreSQL server port

PHOENIX_POSTGRES_USER

string

required

PostgreSQL username

PHOENIX_POSTGRES_PASSWORD

string

PostgreSQL password (not used when AWS IAM auth is enabled)

PHOENIX_POSTGRES_DB

string

required

PostgreSQL database name

PHOENIX_SQL_DATABASE_SCHEMA

string

PostgreSQL schema to use (ignored for SQLite)

AWS RDS IAM Authentication

PHOENIX_POSTGRES_USE_AWS_IAM_AUTH

boolean

default:"false"

Enable AWS RDS IAM database authentication. Requires boto3 installed via pip install 'arize-phoenix[aws]'When enabled:

Do not set PHOENIX_POSTGRES_PASSWORD
AWS credentials must be configured (environment, IAM role, or ~/.aws/credentials)
Database user must be IAM-enabled in RDS/Aurora
SSL is required

PHOENIX_POSTGRES_AWS_IAM_TOKEN_LIFETIME_SECONDS

integer

default:"840"

Token lifetime for connection pool recycling (AWS tokens valid for 15 minutes)

Storage and Retention

PHOENIX_WORKING_DIR

string

default:"~/.phoenix"

Directory for saving, loading, and exporting data. Must be writable by Phoenix.

PHOENIX_DEFAULT_RETENTION_POLICY_DAYS

integer

default:"0"

Automatic trace cleanup after this many days. Set to 0 to disable.

PHOENIX_DATABASE_ALLOCATED_STORAGE_CAPACITY_GIBIBYTES

float

Allocated storage capacity in GiB (for monitoring and alerts)

PHOENIX_DATABASE_USAGE_EMAIL_WARNING_THRESHOLD_PERCENTAGE

float

Send email alerts when storage exceeds this percentage (requires SMTP)

PHOENIX_DATABASE_USAGE_INSERTION_BLOCKING_THRESHOLD_PERCENTAGE

float

Block new insertions when storage exceeds this percentage

Server Configuration

Network Settings

PHOENIX_HOST

string

default:"0.0.0.0"

IP address to bind Phoenix server. Use :: for IPv6.

PHOENIX_PORT

integer

default:"6006"

Port for Phoenix web UI and HTTP API

PHOENIX_GRPC_PORT

integer

default:"4317"

Port for OpenTelemetry gRPC collector

PHOENIX_HOST_ROOT_PATH

string

default:"/"

Root path prefix for Phoenix UI and API (e.g., /phoenix for reverse proxy)

PHOENIX_ROOT_URL

string

External root URL for Phoenix (used in emails and redirects)

PHOENIX_ROOT_URL=https://phoenix.example.com

Performance and Limits

PHOENIX_MAX_SPANS_QUEUE_SIZE

integer

default:"20000"

Maximum spans in processing queue before rejecting requests.Memory usage: ~50KiB per span means 20,000 spans ≈ 1GiB

PHOENIX_ENABLE_PROMETHEUS

boolean

default:"false"

Enable Prometheus metrics endpoint on port 9090

Telemetry and Resources

PHOENIX_TELEMETRY_ENABLED

boolean

default:"true"

Master toggle for analytics tracking (FullStory and Scarf.sh)

PHOENIX_ALLOW_EXTERNAL_RESOURCES

boolean

default:"true"

Allow external resources (Google Fonts, CDNs). Set to false in air-gapped environments.

Authentication and Security

Basic Authentication

PHOENIX_ENABLE_AUTH

boolean

default:"false"

Enable authentication and authorization

PHOENIX_DISABLE_BASIC_AUTH

boolean

default:"false"

Disable password-based authentication (use only OAuth2/LDAP)

PHOENIX_SECRET

string

required

Secret key for JWT signing. Must be:

At least 32 characters
Include at least one digit and one lowercase letter

Generate with:

openssl rand -base64 32

PHOENIX_ADMIN_SECRET

string

Admin secret key for privileged operations

PHOENIX_DEFAULT_ADMIN_INITIAL_PASSWORD

string

default:"admin"

Initial password for default admin user

Token Expiry

PHOENIX_ACCESS_TOKEN_EXPIRY_MINUTES

integer

default:"60"

Access token expiration in minutes

PHOENIX_REFRESH_TOKEN_EXPIRY_MINUTES

integer

default:"43200"

Refresh token expiration in minutes (30 days)

PHOENIX_PASSWORD_RESET_TOKEN_EXPIRY_MINUTES

integer

default:"60"

Password reset token expiration in minutes

Cookies and CORS

PHOENIX_USE_SECURE_COOKIES

boolean

default:"false"

Enable secure cookies (required for HTTPS)

PHOENIX_COOKIES_PATH

string

default:"/"

Cookie path (set when Phoenix is hosted under a sub-path)

PHOENIX_ALLOWED_ORIGINS

string

Comma-separated list of allowed CORS origins:

PHOENIX_ALLOWED_ORIGINS=https://app.example.com,https://dashboard.example.com

PHOENIX_CSRF_TRUSTED_ORIGINS

string

Comma-separated list of trusted origins for CSRF protection:

PHOENIX_CSRF_TRUSTED_ORIGINS=https://phoenix.example.com

Admin Users

PHOENIX_ADMINS

string

Semicolon-separated list of admin users (username=email):

PHOENIX_ADMINS="John [email protected];Jane [email protected]"

Users created with random passwords that must be reset on first login.

LDAP Authentication

See Security Configuration for complete LDAP setup.

PHOENIX_LDAP_HOST

string

LDAP server hostname (comma-separated for failover)

PHOENIX_LDAP_PORT

integer

default:"389"

LDAP server port (389 for StartTLS, 636 for LDAPS)

PHOENIX_LDAP_TLS_MODE

string

default:"starttls"

TLS mode: starttls, ldaps, or none

PHOENIX_LDAP_BIND_DN

string

Service account DN for LDAP binding

PHOENIX_LDAP_USER_SEARCH_BASE_DNS

string

Comma-separated list of base DNs for user search

OAuth2/OIDC

See Security Configuration for provider setup.

PHOENIX_OAUTH2_{PROVIDER}_CLIENT_ID

string

OAuth2 client ID (replace {PROVIDER} with provider name in uppercase)

PHOENIX_OAUTH2_{PROVIDER}_CLIENT_SECRET

string

OAuth2 client secret

PHOENIX_OAUTH2_{PROVIDER}_OIDC_CONFIG_URL

string

OIDC discovery URL (.well-known/openid-configuration)

TLS/SSL Configuration

PHOENIX_TLS_ENABLED

boolean

default:"false"

Enable TLS for Phoenix server

PHOENIX_TLS_ENABLED_FOR_HTTP

boolean

default:"false"

Enable TLS for HTTP endpoints

PHOENIX_TLS_ENABLED_FOR_GRPC

boolean

default:"false"

Enable TLS for gRPC endpoints

PHOENIX_TLS_CERT_FILE

string

Path to TLS certificate file (PEM format)

PHOENIX_TLS_KEY_FILE

string

Path to TLS private key file (PEM format)

PHOENIX_TLS_KEY_FILE_PASSWORD

string

Password for encrypted private key

PHOENIX_TLS_CA_FILE

string

Path to CA certificate for client verification (mutual TLS)

PHOENIX_TLS_VERIFY_CLIENT

boolean

default:"false"

Enable client certificate verification

Email (SMTP) Configuration

PHOENIX_SMTP_HOSTNAME

string

SMTP server hostname

PHOENIX_SMTP_PORT

integer

default:"587"

SMTP server port (typically 587 for TLS, 465 for SSL)

PHOENIX_SMTP_USERNAME

string

SMTP authentication username

PHOENIX_SMTP_PASSWORD

string

SMTP authentication password

PHOENIX_SMTP_MAIL_FROM

string

default:"[email protected]"

Sender email address for system emails

PHOENIX_SMTP_VALIDATE_CERTS

boolean

default:"true"

Validate SMTP server TLS certificates

Logging

PHOENIX_LOGGING_LEVEL

string

default:"info"

Application logging level: debug, info, warning, error, critical

PHOENIX_DB_LOGGING_LEVEL

string

default:"warning"

Database ORM logging level

PHOENIX_LOGGING_MODE

string

default:"default"

Logging format: default or structured (JSON)

PHOENIX_LOG_MIGRATIONS

boolean

default:"true"

Log database migration operations

OpenTelemetry Instrumentation

PHOENIX_SERVER_INSTRUMENTATION_OTLP_TRACE_COLLECTOR_HTTP_ENDPOINT

string

HTTP endpoint for Phoenix server’s own traces

PHOENIX_SERVER_INSTRUMENTATION_OTLP_TRACE_COLLECTOR_GRPC_ENDPOINT

string

gRPC endpoint for Phoenix server’s own traces

Advanced Settings

PHOENIX_DANGEROUSLY_DISABLE_MIGRATIONS

boolean

default:"false"

Disable database migrations (for development only)

Only use during development when switching branches. Can leave database in inconsistent state.

PHOENIX_MIGRATE_INDEX_CONCURRENTLY

boolean

default:"false"

Use CREATE INDEX CONCURRENTLY for PostgreSQL migrations (avoids table locks)

PHOENIX_DISABLE_RATE_LIMIT

boolean

default:"false"

Disable API rate limiting

PHOENIX_MASK_INTERNAL_SERVER_ERRORS

boolean

default:"true"

Mask internal errors in GraphQL/REST responses

Configuration Examples

Development (SQLite)

PHOENIX_PORT=6006
PHOENIX_SQL_DATABASE_URL=sqlite:///phoenix.db
PHOENIX_ENABLE_AUTH=false
PHOENIX_LOGGING_LEVEL=debug

Production (PostgreSQL + Auth)

# Database
PHOENIX_SQL_DATABASE_URL=postgresql://phoenix:${DB_PASSWORD}@postgres.example.com:5432/phoenix
PHOENIX_DEFAULT_RETENTION_POLICY_DAYS=30

# Server
PHOENIX_HOST=0.0.0.0
PHOENIX_PORT=6006
PHOENIX_ROOT_URL=https://phoenix.company.com
PHOENIX_ENABLE_PROMETHEUS=true

# Authentication
PHOENIX_ENABLE_AUTH=true
PHOENIX_SECRET=${PHOENIX_SECRET}
PHOENIX_USE_SECURE_COOKIES=true

# SMTP
PHOENIX_SMTP_HOSTNAME=smtp.gmail.com
PHOENIX_SMTP_PORT=587
PHOENIX_SMTP_USERNAME=[email protected]
PHOENIX_SMTP_PASSWORD=${SMTP_PASSWORD}
PHOENIX_SMTP_MAIL_FROM=[email protected]

# TLS
PHOENIX_TLS_ENABLED_FOR_HTTP=true
PHOENIX_TLS_CERT_FILE=/etc/phoenix/tls/cert.pem
PHOENIX_TLS_KEY_FILE=/etc/phoenix/tls/key.pem

# Logging
PHOENIX_LOGGING_LEVEL=info
PHOENIX_LOGGING_MODE=structured

AWS RDS with IAM Auth

PHOENIX_POSTGRES_HOST=phoenix-db.abc123.us-east-1.rds.amazonaws.com
PHOENIX_POSTGRES_PORT=5432
PHOENIX_POSTGRES_USER=phoenix_iam
PHOENIX_POSTGRES_DB=phoenix
PHOENIX_POSTGRES_USE_AWS_IAM_AUTH=true
PHOENIX_POSTGRES_AWS_IAM_TOKEN_LIFETIME_SECONDS=840

Next Steps

Security

Configure authentication and encryption

Docker

Deploy with Docker and Docker Compose

Kubernetes

Deploy with Kubernetes and Helm

Self-Hosting

Cloud

Configuration Reference

Database Configuration

Connection URL

PostgreSQL Components

AWS RDS IAM Authentication

Storage and Retention

Server Configuration

Network Settings

Performance and Limits

Telemetry and Resources

Authentication and Security

Basic Authentication

Token Expiry

Cookies and CORS

Admin Users

LDAP Authentication

OAuth2/OIDC

TLS/SSL Configuration

Email (SMTP) Configuration

Logging

OpenTelemetry Instrumentation

Advanced Settings

Configuration Examples

Development (SQLite)

Production (PostgreSQL + Auth)

AWS RDS with IAM Auth

Next Steps

Security

Docker

Kubernetes

Build docs developers (and LLMs) love

Self-Hosting

Cloud

​Database Configuration

​Connection URL

​PostgreSQL Components

​AWS RDS IAM Authentication

​Storage and Retention

​Server Configuration

​Network Settings

​Performance and Limits

​Telemetry and Resources

​Authentication and Security

​Basic Authentication

​Token Expiry

​Cookies and CORS

​Admin Users

​LDAP Authentication

​OAuth2/OIDC

​TLS/SSL Configuration

​Email (SMTP) Configuration

​Logging

​OpenTelemetry Instrumentation

​Advanced Settings

​Configuration Examples

​Development (SQLite)

​Production (PostgreSQL + Auth)

​AWS RDS with IAM Auth

​Next Steps

Security

Docker

Kubernetes

Build docs developers (and LLMs) love

Database Configuration

Connection URL

PostgreSQL Components

AWS RDS IAM Authentication

Storage and Retention

Server Configuration

Network Settings

Performance and Limits

Telemetry and Resources

Authentication and Security

Basic Authentication

Token Expiry

Cookies and CORS

Admin Users

LDAP Authentication

OAuth2/OIDC

TLS/SSL Configuration

Email (SMTP) Configuration

Logging

OpenTelemetry Instrumentation

Advanced Settings

Configuration Examples

Development (SQLite)

Production (PostgreSQL + Auth)

AWS RDS with IAM Auth

Next Steps