Skip to main content

​
Overview

This guide covers the three layers of encryption relevant to a production Phoenix deployment:
  1. Encryption in transit: TLS/HTTPS between clients and Phoenix, and between Phoenix and its database
  2. Encryption at rest: encrypting the database and storage that hold your data
  3. Application-level encryption: how Phoenix hashes and encrypts sensitive values before they reach the database
If you haven’t already, take a look at the Phoenix architecture: a single server container backed by a PostgreSQL database.

​
Encryption in Transit (TLS / HTTPS)

Phoenix serves its UI, REST/GraphQL APIs, and OTLP trace collection over HTTP (port 6006) and optionally OTLP over gRPC (port 4317). In production, this traffic should always be encrypted. There are three common approaches.

​
Option 1: Load Balancer / Ingress Termination

TLS is terminated at a load balancer or ingress controller (e.g., AWS ALB, NGINX Ingress), which forwards decrypted traffic to the Phoenix container over HTTP.
  • Pros: Certificate management is typically handled by the cloud provider. This is the most common and straightforward setup.
  • Cons: Traffic between the load balancer and the Phoenix container is unencrypted (though usually confined to a private network).

​
Option 2: Native TLS on the Phoenix Server

Phoenix can terminate TLS itself, with no reverse proxy required:
Remember to point clients at https:// (and configure them with the CA certificate if you use a private CA).

​
Option 3: Service Mesh Sidecar

In Kubernetes environments, a service mesh (e.g., Istio, Linkerd) can transparently encrypt all pod-to-pod traffic with mutual TLS.
  • Pros: End-to-end encryption inside the cluster without application configuration.
  • Cons: Adds operational complexity and requires familiarity with service mesh concepts.

​
Encrypting the Database Connection

Traffic between Phoenix and PostgreSQL should also be encrypted when the database runs outside the Phoenix host or cluster. Phoenix supports standard PostgreSQL SSL parameters (sslmode, sslrootcert, sslcert, sslkey, sslpassword) in the connection string:
When using AWS RDS IAM authentication or Azure Managed Identity, SSL is enforced automatically and cannot be disabled.

​
Other Encrypted Connections

  • LDAP: Use PHOENIX_LDAP_TLS_MODE=starttls (default) or ldaps in production. See Authentication.
  • SMTP: Server certificates are validated by default (PHOENIX_SMTP_VALIDATE_CERTS=true). See Email.
  • Outbound LLM provider calls use HTTPS. To control which endpoints Phoenix can reach, see Network Security.

​
Encryption at Rest

All Phoenix application data (traces, datasets, experiments, prompts, annotations, users, and settings) lives in your database, so encrypting that storage is the main concern. For production deployments we recommend a managed PostgreSQL service such as Amazon RDS/Aurora, Google Cloud SQL, or Azure Database for PostgreSQL. These offer built-in encryption at rest; verify that storage encryption is enabled on the instance and that backups and snapshots are encrypted. For self-managed PostgreSQL, use disk or volume-level encryption (e.g., LUKS, encrypted EBS volumes, encrypted Kubernetes persistent volumes) on the data directory. Database dumps, snapshots, and exported data are just as sensitive as the database itself and should be stored on encrypted media.

​
Application-Level Encryption

Beyond transport and storage encryption, Phoenix hashes or encrypts sensitive values at the application layer before persisting them, so they are not readable in plaintext even with direct database access. All of these protections are anchored by the PHOENIX_SECRET environment variable. It must be at least 32 characters and include at least one digit and one lowercase letter:
Treat PHOENIX_SECRET like a master key:
  • Use a long, random value and store it in a secrets manager (e.g., Kubernetes Secrets, AWS Secrets Manager, HashiCorp Vault). Never keep it in plaintext configuration or images, and never alongside database backups.
  • Changing PHOENIX_SECRET invalidates existing sessions and API keys, and makes previously encrypted credentials (e.g., stored AI provider API keys) undecryptable. They must be re-entered after rotation.
Application-level encryption protects against exposure of database backups and dumps. It does not protect against an attacker who obtains both the database and PHOENIX_SECRET.
For related hardening guidance, see Network Security, Authentication, and Access Control (RBAC).