SELF-HOSTING

Docker Compose

Learn how to set up the Phase Console using the Docker Compose template.

AI Deployment Skill

docker-compose
$ npx skills add phasehq/ai -s docker-compose

Then 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

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.

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

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 the frontend service at http://frontend:3000.
  • Requests to https://<your-host-ip-address>/service/* are routed to the backend service at http://backend:8000, with the /service path 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"}