Docker Compose
Learn how to set up the Phase Console using the Docker Compose template.
$ npx skills add phasehq/ai -s docker-composeThen ask your agent to deploy Phase with Docker Compose
The steps outlined below provide a general guide for self-hosting Phase Services on your own infrastructure.
Important considerations:
- It's recommended to run the Phase Service behind a VPN or within a VPC, rather than exposing it directly to the internet.
- You may need to configure additional components such as TLS certificates, web application firewalls, database backups and replication, DDoS protection, rate limiting, and SSO.
1. Install Docker on your machine
First, download the official Docker installation script:
curl https://get.docker.com > install.sh && chmod +x install.sh
We recommend reviewing the script before executing it on your system.
Install Docker and Docker Compose:
sh install.sh
Add your user to the Docker group:
sudo usermod -aG docker $USER
You will need to log out and log back in for the group changes to take effect. You may use Ctrl + D to log out and then SSH back in.
Verify that Docker is running:
docker ps
2. Download the configuration files
.env template:
wget -O .env https://raw.githubusercontent.com/phasehq/console/main/.env.example
Docker Compose template:
You can review the docker compose configuration 👉 here.
wget -O docker-compose.yml https://raw.githubusercontent.com/phasehq/console/main/docker-compose.yml
Nginx config:
mkdir nginx && wget -O ./nginx/default.conf https://raw.githubusercontent.com/phasehq/console/main/nginx/default.conf
Nginx Dockerfile:
wget -O ./nginx/Dockerfile https://raw.githubusercontent.com/phasehq/console/main/nginx/Dockerfile
3. Update your configuration
Modify the .env file to match your environment settings.
Generate secrets
sed -i.bak "s|DATABASE_PASSWORD=.*|DATABASE_PASSWORD=$(openssl rand -hex 32)|g" .env && \
sed -i.bak "s|SECRET_KEY=.*|SECRET_KEY=$(openssl rand -hex 32)|g" .env && \
sed -i.bak "s|SERVER_SECRET=.*|SERVER_SECRET=$(openssl rand -hex 32)|g" .env && \
rm .env.bak
For a complete list of available options, refer to the environment variables documentation.
For a production deployment, please use a more secure method than a .env file to store your secrets. Please see our guide on Docker Compose secrets for more information.
4. Start services
Pull containers and start services:
docker compose up -d
Your Phase Console deployment will be accessible at https://<your-host-ip-address>. By default, Phase provisions a self-signed TLS certificate using Nginx. For production use, please configure a valid TLS certificate for your domain.
Upgrade
Check the release notes for anything you need to do before upgrading, and back up your database. See Database Migrations when Upgrading Phase for details.
To upgrade Phase and the bundled Nginx reverse proxy, run:
docker compose pull
docker compose build --pull nginx
docker compose up -d
docker compose pull updates the Phase frontend and backend images. The nginx service is different: Docker Compose builds it on your machine from nginx/Dockerfile, which uses the latest official Nginx image. docker compose pull skips it, and docker compose up -d keeps using the image that was built the first time you started Phase. docker compose build --pull nginx rebuilds it on the latest Nginx release.
Nginx is the only Phase service exposed to the internet, so rebuild it regularly, even between Phase releases, to pick up Nginx security fixes. To check which version you are running:
docker compose exec nginx nginx -v
Nginx 1.31.8 and earlier are affected by CVE-2026-123007 and related vulnerabilities, which allow remote code execution over HTTP/2. If your Nginx image was built before November 18, 2026, run docker compose build --pull nginx && docker compose up -d nginx and confirm the version is 1.31.9 or later.
Stop services
To stop the Phase Console services, run:
docker compose down
Uninstall
To completely remove the Phase Console and delete all data (including the database), run:
docker compose down -v
Troubleshooting
In case you encounter any issues, please refer to the troubleshooting section below.
Routing Structure
The nginx service acts as a reverse proxy for the frontend and backend services.
- Requests to
https://<your-host-ip-address>/*are routed to thefrontendservice athttp://frontend:3000. - Requests to
https://<your-host-ip-address>/service/*are routed to thebackendservice athttp://backend:8000, with the/servicepath prefix stripped.
Health Checks
You can check the health of the services using curl. Since a self-signed certificate is used by default, you may need to use the -k or --insecure flag to bypass certificate validation.
-
Frontend Health Check:
curl -vk https://<your-host-ip-address>/api/health # Expected response: {"status":"alive"} -
Backend Health Check:
curl -vk https://<your-host-ip-address>/service/health/ # Expected response: {"status": "alive", "version": "x.x.x"}