Deploy Phoenix in a containerized environment using Docker or Docker Compose.
Quick Start with Docker
Run Phoenix as a standalone container:
docker run -d \
--name phoenix \
-p 6006:6006 \
-p 4317:4317 \
arizephoenix/phoenix:latest
http://localhost:6006
Docker Compose Deployment
For production deployments, use Docker Compose with PostgreSQL for persistence.
docker-compose.yml
services:
phoenix:
image: arizephoenix/phoenix:latest
depends_on:
- db
ports:
- 6006:6006 # Phoenix UI and API
- 4317:4317 # OpenTelemetry gRPC endpoint
environment:
- PHOENIX_SQL_DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres
- PHOENIX_ENABLE_AUTH=true
- PHOENIX_SECRET=${PHOENIX_SECRET}
restart: unless-stopped
db:
image: postgres:16
restart: always
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres
- POSTGRES_DB=postgres
ports:
- 5432
volumes:
- database_data:/var/lib/postgresql/data
volumes:
database_data:
driver: local
Start the Services
Set environment variables
Create a .env file with your secrets:PHOENIX_SECRET=$(openssl rand -base64 32)
Launch containers
Start Phoenix and PostgreSQL: Verify deployment
Check that containers are running:docker-compose ps
docker-compose logs phoenix
Building from Source
Build the Phoenix image from the Dockerfile:
# Clone the repository
git clone https://github.com/Arize-ai/phoenix.git
cd phoenix
# Build the image
docker build -t phoenix .
# Run the container
docker run -d --name phoenix -p 6006:6006 -p 4317:4317 phoenix
Multi-Stage Build
The Dockerfile uses a multi-stage build process:
- Frontend Builder: Builds the React application using Node.js and pnpm
- Backend Builder: Packages the Python application with uv
- Production Image: Distroless Python image for minimal attack surface
Environment Variables
Configure Phoenix using environment variables:
Database connection URL. Use PostgreSQL for production:postgresql://user:password@host:5432/dbname
Enable authentication and authorization
Secret key for JWT signing (min 32 characters, alphanumeric with digits)
Port for the Phoenix web UI and HTTP API
Port for the OpenTelemetry gRPC collector
Persistence
PostgreSQL (Recommended)
Use PostgreSQL with a named volume for production:
volumes:
database_data:
driver: local
SQLite (Development Only)
For development, mount a volume for SQLite:
phoenix:
volumes:
- phoenix_data:/data
environment:
- PHOENIX_WORKING_DIR=/data
volumes:
phoenix_data:
SQLite is not recommended for production. Use PostgreSQL for better performance and reliability.
Exposed Ports
The Phoenix container exposes three ports:
- 6006: Phoenix web UI and HTTP API
- 4317: OpenTelemetry gRPC endpoint for trace ingestion
- 9090: Prometheus metrics (when enabled)
Health Checks
Phoenix provides health check endpoints:
/healthz: Liveness probe/readyz: Readiness probe
Add health checks to your docker-compose.yml:
phoenix:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:6006/healthz"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
ARM64 Support
For ARM64 platforms (Apple Silicon, Raspberry Pi), use the ARM64 base image:
ARG BASE_IMAGE=gcr.io/distroless/python3-debian12:nonroot-arm64
Troubleshooting
Container Fails to Start
Check logs for errors:
Database Connection Issues
Verify PostgreSQL is accessible:
docker exec -it phoenix-db-1 psql -U postgres -c "\l"
Permission Issues
The container runs as non-root user (UID 65532). Ensure volumes have correct permissions:
chown -R 65532:65532 /path/to/volume
Next Steps
Configuration
Configure environment variables and settings
Security
Set up authentication and encryption
Kubernetes
Deploy with Kubernetes and Helm