Install Arize Phoenix with Docker for Self-Hosted LLM and AI Agent Observability

If you want to understand what your LLM agents are doing, you need tracing set up before things break in production. This guide shows you how to self-host Arize Phoenix with Docker.

By the end, you'll have a persistent, HTTPS-secured Phoenix instance running on your own Linux VPS. It captures real traces from a Python agent, retrieval steps, tool calls, and LLM spans, not just a single model call.

Arize Phoenix is an open-source tool for monitoring and evaluating AI systems. Built on OpenTelemetry and OpenInference, it lets you trace LLM calls, RAG retrieval, and agent tool calls, all in one dashboard. Teams self-host Phoenix with Docker instead of using the managed cloud version, mainly to keep prompts, embeddings, and customer data inside their own infrastructure.

Running your own observability stack has real benefits:

• No vendor lock-in, sensitive data stays off third-party servers.
• You control retention and storage costs.

A dedicated Linux VPS with enough RAM and disk gives you the isolation this needs, since tracing volume can spike fast during heavy agent testing.

Anyone planning to self-host Arize Phoenix with Docker in production should confirm these requirements first:

• A Linux VPS running Ubuntu 24.04 with at least 2 vCPU, 4GB RAM, and 40GB SSD storage.
• Docker Engine and Docker Compose v2 are installed and running.
• A domain name pointed at your VPS if you plan to expose Phoenix over HTTPS.
• Root or sudo access to configure firewall rules and the reverse proxy.
• An OpenAI or other LLM provider API key for the demo agent will be used later.

Update your packages and confirm Docker is installed on your server:

Create a dedicated working directory to keep this deployment isolated from other services:

Persistent storage is essential if you want to self-host Arize Phoenix with Docker without losing traces on every restart. This setup uses PostgreSQL for the trace database and a named volume for working files.

First, create two different 32-character secrets for Phoenix with:

Create a .env file to hold secrets outside version control:

Now, create docker-compose.yml file with your desired text editor:

Add:

Save and close the file. This compose file is the core step to self-host Arize Phoenix with Docker and a database that survives container recreation, upgrades, or a host reboot.

Note: Authentication is off by default in Phoenix, so setting PHOENIX_ENABLE_AUTH=True alongside a strong PHOENIX_SECRET is essential before exposing the server to the internet.

The PHOENIX_ADMIN_SECRET variable serves as a bootstrap bearer token, authenticating as the first system user and allowing your agent to send data immediately without requiring a UI login.

Exposing Phoenix directly on port 6006 without TLS is risky for anything beyond local testing, so front it with Caddy for automatic HTTPS.

From inside ~/phoenix-stack, create the Caddyfile with your actual domain name:

Note that phoenix:6006 refers to Caddy reaching the Phoenix container by its service name on the internal Docker network, not localhost. Compose automatically creates a shared network where containers resolve each other by service name.

Then, add the Caddy service to the Compose file. Edit the file:

Add this new caddy service block, indented the same as phoenix and db:

Then add the two new named volumes to the existing volumes: section at the bottom of the file, alongside phoenix_data and phoenix_db_data:

Save and close the file once you are done.

You must restrict access so that only trusted IPs and your application servers can reach Phoenix's ports. On Ubuntu with UFW, run:

Blocking direct access to ports 6006 and 4317 means all traffic must pass through Caddy's TLS encryption. If your agent runs on a different server, don't block 4317 completely; only allow that server's IP to reach it.

With the compose file and network rules ready, you are ready for deployment. Run this command to bring up the stack:

Check your Docker Compose status:

It must be UP.

Check the logs with:

Once the logs show the server is ready, in your browser, open:

You will see the login screen. Enter the default credentials:

Then, change the default password immediately and log in:

You must see the Phoenix UI:

You have now completed the core installation with persistent Postgres storage, HTTPS, and firewall rules in place.

A single model call won't show you what real observability looks like. So this section builds a LangChain agent that does retrieval and a tool call, then sends both to your self-hosted Phoenix.

On the machine running your agent, this can be the same VPS or a separate application server, as long as it can reach your Phoenix domain, confirm Python and pip are available:

Keeping this in a venv avoids polluting your system Python and prevents version conflicts with other projects on the same server:

Now run the actual install, inside the activated venv:

Verify the installation with:

If it prints OK with no import errors, the environment is ready.

At this point, use the command below to create the Agent script file:

Add:

Save and close the file.

Still inside the activated venv, point the OTLP endpoint and auth header at your Phoenix server:

Then, run the script:

This script runs a retrieval step, an LLM call, and a tool call, giving you the three span types a real agent produces, instead of the single trace you'd get from just calling an LLM API directly.

Open your Phoenix UI and click into the project your agent run created. You should see a trace tree with three spans:

• A retriever span showing the documents pulled from FAISS.
• An LLM span showing the prompt and completion.
• A tool span for get_server_status.

If any span is missing, it's usually because the OTLP endpoint or auth header was set up incorrectly on the agent side. Check PHOENIX_COLLECTOR_ENDPOINT and the bearer token first.

To add evaluation spans, run Phoenix's built-in evals on your traces after the run finishes. These score things like retrieval relevance or hallucination. Then log the results back to the same trace ID so they show up alongside the original spans in the UI.

Snapshot your phoenix_db_data and phoenix_data volumes on a schedule, and store copies off the VPS in case you need to roll back after a bad upgrade.

Keeping backups healthy on a Linux VPS with enough storage and root access lets you repair issues safely without losing months of trace history, since Postgres restores sometimes need direct filesystem work.

If your traffic grows, it's worth comparing this stack against another observability option like the one covered in PerLod's self-hosted SigNoz with Docker guide to decide which fits your team better.

You now have a repeatable way to run this stack with persistent Postgres storage, HTTPS via Caddy, firewall-restricted ports, and a working agent that produces retrieval, LLM, and tool-call spans. From here, add more agents, tune retention with PHOENIX_DEFAULT_RETENTION_POLICY_DAYS, and keep backups current so your trace history survives future upgrades.

We hope you enjoy this guide on how to self-host Arize Phoenix with Docker.

For more deployment options and configurations, check the Arize Phoenix official self-hosting documentation.