Environment:Arize ai Phoenix Phoenix Server Runtime

Knowledge Sources	Arize Phoenix DEVELOPMENT.md
Domains	Infrastructure, AI_Observability
Last Updated	2026-02-14 06:00 GMT

Overview

Phoenix server runtime environment with FastAPI, gRPC, SQLite/PostgreSQL database, and extensive environment variable configuration.

Description

This environment provides the full runtime context for running the Phoenix AI observability server. The server is a FastAPI application with both HTTP (REST + GraphQL) and gRPC endpoints for OTLP span ingestion. It supports SQLite (default, in-memory or file-based) and PostgreSQL for data persistence.

The server uses Alembic for database migrations, Strawberry for GraphQL, and supports authentication via local passwords, OAuth2/OIDC, and LDAP. TLS can be enabled for both HTTP and gRPC endpoints.

Usage

Use this environment when running the Phoenix server for collecting traces, serving the UI, and exposing APIs. It is required for any deployment scenario: local development, Docker, Kubernetes (Helm/Kustomize).

System Requirements

Category	Requirement	Notes
OS	Linux, macOS	Windows supported but uvloop unavailable
Python	>= 3.10, < 3.14	Server requires full Phoenix package
Ports	6006 (HTTP), 4317 (gRPC)	Configurable via environment variables
Database	SQLite or PostgreSQL 16+	PostgreSQL recommended for production
Disk	1GB+	For SQLite database and static assets

Dependencies

Server Framework

`fastapi`
`starlette`
`uvicorn`
`strawberry-graphql[opentelemetry]` == 0.287.3
`grpcio`
`grpc-interceptor`
`py-grpc-prometheus` (container extra)

Database

`sqlalchemy[asyncio]` >= 2.0.4, < 3
`alembic` >= 1.3.0, < 2
`aiosqlite` (SQLite async driver)
`asyncpg` (PostgreSQL async driver, pg extra)
`psycopg[binary,pool]` (PostgreSQL driver, pg extra)

Authentication

`authlib`
`ldap3`
`pyjwt`
`email-validator`

Optional Production

`uvloop` (Linux/macOS only, container extra)
`prometheus-client` (container extra)

Credentials

Server Configuration:

`PHOENIX_PORT`: HTTP port (default: 6006)
`PHOENIX_GRPC_PORT`: gRPC port (default: 4317)
`PHOENIX_HOST`: Bind address (default: 0.0.0.0)
`PHOENIX_HOST_ROOT_PATH`: URL path prefix (must start with `/`, cannot end with `/`)
`PHOENIX_SQL_DATABASE_URL`: Database URL (e.g., `sqlite:///data/phoenix.db` or `postgresql://user:pass@host:5432/db`)
`PHOENIX_WORKING_DIR`: Working directory for data storage

Authentication:

`PHOENIX_SECRET`: Secret key for token signing
`PHOENIX_ENABLE_AUTH`: Enable authentication (True/False)
`PHOENIX_API_KEY`: API key for programmatic access

Email/SMTP:

`PHOENIX_SMTP_HOSTNAME`: SMTP server for email notifications
`PHOENIX_SMTP_PORT`: SMTP port (default: 587)
`PHOENIX_SMTP_USERNAME`: SMTP username
`PHOENIX_SMTP_PASSWORD`: SMTP password

TLS:

`PHOENIX_TLS_ENABLED`: Enable TLS globally
`PHOENIX_TLS_ENABLED_FOR_HTTP`: Enable TLS for HTTP only
`PHOENIX_TLS_ENABLED_FOR_GRPC`: Enable TLS for gRPC only
`PHOENIX_TLS_CERT_FILE`: Path to TLS certificate file
`PHOENIX_TLS_KEY_FILE`: Path to TLS private key file
`PHOENIX_TLS_KEY_FILE_PASSWORD`: Password for TLS key file
`PHOENIX_TLS_CA_FILE`: CA file for client certificate verification
`PHOENIX_TLS_VERIFY_CLIENT`: Enable mTLS client verification

Other:

`PHOENIX_TELEMETRY_ENABLED`: Enable usage telemetry (default: True)
`PHOENIX_DEFAULT_RETENTION_POLICY_DAYS`: Auto-delete traces after N days (default: 0 = disabled)

Quick Install

# Basic server (SQLite)
pip install arize-phoenix

# Server with PostgreSQL support
pip install "arize-phoenix[pg]"

# Full production deployment
pip install "arize-phoenix[container]"

# Run the server
phoenix serve

# Run with in-memory database (fresh start)
PHOENIX_SQL_DATABASE_URL=sqlite:///:memory: phoenix serve

# Docker deployment
docker-compose up

Code Evidence

Default port configuration from `packages/phoenix-client/src/phoenix/client/constants.py:18-19`:

HOST = "0.0.0.0"
PORT = 6006

TLS validation from `src/phoenix/config.py:872-873`:

if not (cert_file_str := getenv(ENV_PHOENIX_TLS_CERT_FILE)):
    raise ValueError("PHOENIX_TLS_CERT_FILE must be set when PHOENIX_TLS_ENABLED is true")

Host root path validation from `packages/phoenix-client/src/phoenix/client/utils/config.py:40-52`:

def get_env_host_root_path() -> str:
    if (host_root_path := getenv(ENV_PHOENIX_HOST_ROOT_PATH)) is None:
        return ""
    if not host_root_path.startswith("/"):
        raise ValueError(f"Invalid value... Value must start with '/'")
    if host_root_path.endswith("/"):
        raise ValueError(f"Invalid value... Value cannot end with '/'")
    return host_root_path

Docker Compose setup from `docker-compose.yml:11-12`:

environment:
  - PHOENIX_SQL_DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres

Common Errors

Error Message	Cause	Solution
`PHOENIX_TLS_CERT_FILE must be set`	TLS enabled but no cert file	Set PHOENIX_TLS_CERT_FILE path
`Value must start with '/'`	Invalid PHOENIX_HOST_ROOT_PATH	Ensure path starts with `/` and does not end with `/`
`PHOENIX_DEFAULT_RETENTION_POLICY_DAYS must be non-negative`	Negative retention days	Set to 0 or a positive integer
`asyncpg not installed`	PostgreSQL URL but no pg driver	`pip install "arize-phoenix[pg]"`

Compatibility Notes

SQLite: Default for development and small deployments. Uses `sqlean.py` for enhanced SQLite features. Supports in-memory mode with `sqlite:///:memory:`.
PostgreSQL: Recommended for production. Requires PostgreSQL 16+. Docker Compose provides a ready-to-use setup.
Windows: `uvloop` is not available. The server falls back to the default asyncio event loop.
Kubernetes: Deployment manifests are provided in `kustomize/` and `helm/` directories.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment