docs
SELF-HOSTING

Azure

Learn how to set up the Phase Console using Azure Virtual Machines and Azure Database for PostgreSQL via the Docker Compose template.

Keep in mind the steps listed below serve as a rough outline on how to self-hosting Phase Services on your own infrastructure.

You may:

  • Choose to run the Phase Console components on managed services (PaaS) or alternative container orchestration tools like Kubernetes instead of Docker Compose.
  • Consider running the Phase Service behind a VPN or a VPC and not to expose it the internet directly.
  • Need to set up things like TLS certificates, web application firewall, database backups and replication, DDoS protection, rate limiting, SSOs etc.

I. Set Up an Azure Virtual Machine (VM)

  1. Log in to the Azure Portal.

  2. Navigate to Virtual Machines and click on Add to create a new VM.

  3. Basics tab:

    • Resource Group: Create a new one or select an existing.
    • Virtual machine name: Enter a unique name.
    • Region: Choose a preferred region.
    • Image: Select Ubuntu Server 22.04 LTS.
    • Size: Choose a size, ideally Standard_D2s_v3.

  4. Disks tab:

    • Choose Standard SSD.
    • Set the size to 120GB.

  5. Networking tab:

    • Choose or create a VNet and Subnet.
    • Public IP: Ensure it's enabled.
    • NIC network security group: Select Advanced.
    • Add inbound port rules to allow HTTP (port 80), HTTPS (port 443), and SSH (port 22).

  6. Management tab:

    • Under Boot diagnostics, select On.

  7. Review + create: Review your configurations and click Create.

  8. SSH Key Pair:

    • While still under the Basics tab, for Authentication type, choose SSH public key.
    • Generate SSH keys following Azure’s guide and provide the public key.

II. Set Up Azure Database for PostgreSQL

  1. In the Azure portal, navigate to Azure Database for PostgreSQL and click on Add.

  2. Basics tab:

    • Resource Group: Select the one used for the VM.
    • Database name: Enter a unique name.
    • Location: Preferably the same as your VM for latency purposes.
    • Version: Choose 15.

  3. Configuration:

    • Set up the compute and storage according to your needs (ideally Compute Gen 5 2 core, 10GiB Memory).

  4. Networking:

    • Choose the method Allow access to Azure services to let the VM connect.
    • Ensure the VNet from your VM is connected.

  5. Review + create: Review your configurations and click Create.

III. Set Up Azure Cache for Redis

  1. In the Azure portal, navigate to Azure Cache for Redis and click on Add.

  2. Basics tab:

    • Resource Group: Select the one used for the VM.
    • DNS name: Enter a unique DNS name.
    • Location: Preferably the same as your VM.
    • Pricing tier: Choose a tier that suits your needs (e.g., Basic C0 for testing).

  3. Networking:

    • Make sure the Redis instance is accessible from your VM's subnet.

  4. Security:

    • Enable non-SSL port if necessary (not recommended for production).
    • Set a strong access key.

  5. Review + create: Review your configurations and click Create.

  6. Note down the host name and access keys for later use.

IV. SSH into the VM & Setup Database

  1. Navigate to the directory containing your private SSH key.

  2. SSH into your Azure VM:

    ssh -i "path-to-your-private-key" azureuser@your-vm-public-ip

  3. Install PostgreSQL client:

    sudo apt update
sudo apt install postgresql-client

  4. Connect to the Azure PostgreSQL database:

    psql -h your-azure-postgresql-endpoint -U your-username -d postgres

  5. Database setup:

    CREATE DATABASE phase_db;
CREATE USER phase_api WITH PASSWORD 'your-password';
GRANT ALL PRIVILEGES ON DATABASE phase_db TO phase_api;

  6. Exit the PostgreSQL session:

    \q

IV. Prepare for Docker Deployment

  1. Generate a strong database password:

    openssl rand -hex 32

  2. Install Docker & Docker Compose:

    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

  3. Download required configurations:

    • .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 & Dockerfile:

      mkdir nginx && wget -O ./nginx/default.conf https://raw.githubusercontent.com/phasehq/console/main/nginx/default.conf
wget -O ./nginx/Dockerfile  https://raw.githubusercontent.com/phasehq/console/main/nginx/Dockerfile

  4. Edit .env file:

    • Replace DATABASE_HOST with your Azure PostgreSQL endpoint.
    • Update DATABASE_NAME, DATABASE_USER, and DATABASE_PASSWORD with your credentials.
    • Add REDIS_HOST, REDIS_PORT, and REDIS_PASSWORD and set them to your Azure Cache for Redis host, port (6379), and access key.
    • Modify other environment variables as necessary.

    Generate secrets

    You can use the following command to generate strong random secrets for your .env file:

    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.

  5. Edit docker-compose.yml:

    • Comment out the PostgreSQL service.
    • Comment out the Redis service.

  6. Start services:

    Pull containers and start services:

    docker compose up -d

  7. You should now be able to access the Phase console at https://your-vm-public-ip. By default, Phase provisions a self-signed TLS certificate using Nginx. For production use, please configure a valid TLS certificate for your domain.

Stop services

To stop the Phase Console services, run:

docker compose down

Uninstall

To completely remove the Phase Console and delete all data (excluding external databases), run:

docker compose down -v

Troubleshooting

Routing Structure

The nginx service acts as a reverse proxy for the frontend and backend services.

  • Requests to https://your-vm-public-ip/* are routed to the frontend service at http://frontend:3000.
  • Requests to https://your-vm-public-ip/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-vm-public-ip/api/health
# Expected response: {"status":"alive"}

  • Backend Health Check:

    curl -vk https://your-vm-public-ip/service/health/
# Expected response: {"status": "alive", "version": "x.x.x"}