deploy-phoenix-with-kamal.md

Create a Droplet on e.g. DigitalOcean.
- Make sure it has at least 1 vCPU and 1 GB of memory.
- Mine has: 1 vCPU, 1 GB, 35 GB NVMe SSD, Premium Intel CPU, Ubuntu 24.04 LTS for $8/month on Digital Ocean
- Choose SSH KEY AUTHENTICATION and create a new SSH key.
- Remember the server's IPv4 address.
Sign up for a Container Registry e.g. on Digital Ocean for $5/mo (the 500MB free plan won't cut it)
- Remember your username on the registry
Create an API Token at https://cloud.digitalocean.com/account/api/tokens for pushing images to the registry.
- It needs to have these scopes: registry (4): delete, update, read, create
Install Kamal with gem install kamal
Run kamal init
Edit the config/deploy.yml like this:

# config/deploy.yml

service: <SOME_SERVICE_NAME>

image: <YOUR_REGISTRY_USERNAME>/<YOUR_APP_NAME>

servers:
  web:
    - <YOUR_SERVER_IP_ADDRESS>
proxy:
  ssl: true
  host: peterullrich.com
  app_port: 4000

registry:
  server: registry.digitalocean.com
  username: <YOUR_REGISTRY_USERNAME>
  password:
    - KAMAL_REGISTRY_PASSWORD

# I had troubles building the amd64 container on my arm64 M2 macbook.
# That's why I build the container either on my server with the `remote` option
# or eventually in my GitHub Action (see script below)
builder:
  arch: amd64
  remote: ssh://root@<YOUR_SERVER_IP_ADDRESS>

env:
  clear:
    PORT: 4000
    MIX_ENV: prod
    PHX_HOST: <YOUR_PHX_HOST>
  secret:
    - SECRET_KEY_BASE
    - DATABASE_URL # If you want to create the database outside of Kamal with e.g. Supabase or Neon. I haven't figured out yet how to deploy a Postgres instance with Kamal.

# I like to add these aliases to make it easier to start a bash shell or an IEx session in the container.
aliases:
  bash: app exec -q -p -i --reuse bash
  remote: app exec -q -p -i --reuse "/app/bin/<YOUR_APP_NAME> remote"

Update your .kamal/secrets and set all env variables that you've set under env.secret above plus the KAMAL_REGISTRY_PASSWORD one.

# .kamal/secrets
KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
SECRET_KEY_BASE=$SECRET_KEY_BASE

(If you need a Database and host it somewhere else)
DATABASE_URL=$DATABASE_URL

Add a GitHub Action that builds and deploys the container.

# .github/workflows/deploy.yml

name: Deploy
on:
  push:
    branches:
      - main
jobs:
  deploy:
    name: Deploy app
    runs-on: ubuntu-24.04
    concurrency: deploy-group # optional: ensure only one action runs at a time
    env:
      DOCKER_BUILDKIT: 1 # No clue what these two env variables. I copied them from another blog and haven't removed them since.
      RAILS_ENV: production
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true

      - run: gem install kamal -v 2.4.0

      - uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - run: kamal deploy
        env:
          KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}
          SECRET_KEY_BASE: ${{ secrets.SECRET_KEY_BASE }}
          # ADD ALL ENVIRONMENT VARIABLES THAT YOU NEED IN THE CONTAINER HERE!

Add your environment secrets to the GitHub Action. You need at least:
- SSH_PRIVATE_KEY
- KAMAL_REGISTRY_PASSWORD
- SECRET_KEY_BASE
- DATABASE_URL # optional, only if you've configured it above as well
Now add a Dockerfile to your project with mix phx.gen.release --docker
Add an EXPOSE 4000 just before your CMD ["/app/bin/server"] in the end of the Dockerfile.
Add this as rel/env.sh.eex:

#!/bin/sh

# These env variables run before the mix release is started.
HOSTNAME=$(hostname -f)

export DNS_CLUSTER_QUERY=$HOSTNAME
export RELEASE_DISTRIBUTION="name"
export RELEASE_NODE="<YOUR_APP_NAME>@${HOSTNAME}"

Add the environment variables above also to a local .env file and source it into your terminal with source .env
Run kamal server bootstrap. This will configure your server for you.
Commit your changes and push it to GitHub! I wrote the instructions above from memory and haven't tested them yet. But they "should" work and your Phoenix app should now run on your Server!
(Optional) Add your domain to Digital Ocean and connect it with the Droplet. Then update your nameservers to the ones from Digital Ocean and within a few minutes, you should see your Phoenix app under your domain!
(Optional) Add a Firewall to your Droplet on Digital Ocean and only allow TCP/UDP from IPv4 or IPv6 connections and SSH from IPv4. Ideally, you only allow SSH connections from your own IP and the GitHub Runner, but unless you pay for a larger GitHub Runner, its IP won't be static and it won't be able to connect to your server anymore. That's why I have it on SSH: All IPv4. Not great but okay for now.

These two blog posts have helped a lot:

PJUllrich/deploy-phoenix-with-kamal.md