Skip to content
Halo

Documentation

Self-hosting guide

Halo runs on your own infrastructure with no external services: a Go server, a Next.js web interface, PostgreSQL, and a reverse proxy that terminates TLS. The repository ships everything needed to run it on one host with Docker Compose. This page is the step-by-step guide: DNS, the environment file, starting the services, the first administrator, backups, upgrades, health checks and rotating HALO_SECRET_KEY.

What runs

Text
internet ──► caddy :80 :443 ──► halo-web :3200 ──► halo-server :8080 ──► postgres :5432
Service Image What it does
postgres postgres:17-alpine Stores everything in the postgres volume.
halo-server ghcr.io/scalastudios/halo-server Runs halo serve: applies database migrations on every start, then serves the API and the OpenID Connect endpoints.
halo-web ghcr.io/scalastudios/halo-web Serves the console, sign-in pages and account portal, and forwards /api, /oauth2, /.well-known, /saml and /scim to halo-server.
caddy caddy:2 Terminates TLS for HALO_DOMAIN and sends every request to halo-web.

Only Caddy publishes ports. The other services are reachable only on the internal halo network. halo-server is a static Go binary on a distroless base that runs as a non-root user, and halo-web is a Next.js standalone server on Node.js 22. Both images are published for linux/amd64 and linux/arm64, so nothing is built on the host. They are built from deploy/Dockerfile.server and deploy/Dockerfile.web.

Decide before you install

  • The domain. Halo's address is the OpenID Connect issuer that every application stores, and passkeys only work on the hostname they were created for. Moving Halo to a new hostname later means reconfiguring every application and giving everyone a new setup link. Pick a name you intend to keep, such as auth.example.com.
  • The secret key. HALO_SECRET_KEY encrypts the token signing keys, authenticator-app secrets and other stored secrets, and a database backup is useless without the key that was in use when it was taken. Store it in your password manager when you create it. To replace it, stop Halo and run halo rotate-secret-key as described in Rotate HALO_SECRET_KEY; recovery codes do not survive a rotation, so the people who had them generate new ones.
  • One server or several. One server is enough for most installations. On v0.2.0, multiple servers can share a PostgreSQL database and coordinate background jobs. See Running several instances.
  • Email. Halo works without email: invite and reset links are shown to the administrator who creates them, to pass on. With an SMTP server in the HALO_SMTP_* variables, Halo also emails those links and people can sign in with magic links. Configuration lists every variable.

Before you start

  • A Linux host, amd64 or arm64, with Docker Engine and the Docker Compose plugin. The install script installs both when you run it as root on a host without Docker. These files were tested with Docker 29.8 and Docker Compose 5.5.
  • A domain name for Halo, such as auth.example.com.
  • Ports 80 and 443 on the host reachable from the internet, so Caddy can obtain and renew the certificate.
  • compose.yml, Caddyfile and .env.example from the deploy directory on the host. The install script downloads them for you.

Install with the script

Point your domain at the host first, as in step 1 of Install, then run:

Bash
curl -fsSL https://halo.scala.gg/install.sh | sh

The script needs curl and openssl. When Docker isn't installed and you run the script as root, it first installs Docker with Docker's own script from get.docker.com. It asks for your domain and organization name, or reads them from HALO_DOMAIN and HALO_ORGANIZATION. It installs into /opt/halo when run as root and ~/halo otherwise, or into HALO_DIR. That directory then holds everything Halo needs on the host:

File What it is
halo.sh The install script, to manage Halo afterwards
compose.yml, Caddyfile The files from deploy, for the release it installed
.env Your domain and organization, a new database password and HALO_SECRET_KEY
halo.sh.log The output of every install and update step. When a step fails, the script prints its last lines

Manage Halo with halo.sh:

Command What it does
./halo.sh admin you@example.com "Your Name" Creates the first global administrator and prints a link to enroll a passkey
./halo.sh start, stop Starts or stops every service
./halo.sh restart Recreates every service, which also applies changes to .env
./halo.sh update Updates to the version pinned by the public installer
./halo.sh logs [service] Follows the logs of every service, or of one
./halo.sh help Lists the commands

Read the script before you run it if you prefer: it is deploy/install.sh in the Halo repository.

Install

  1. Point an A record (and an AAAA record if the host has IPv6) for your domain at the host, and wait until it resolves.

  2. Create the environment file from a checkout of the repository:

    Bash
    cd deploy
    cp .env.example .env
    
  3. Edit .env and set these values:

    Variable Set it to
    HALO_DOMAIN Your domain, for example auth.example.com.
    POSTGRES_PASSWORD The output of openssl rand -hex 32. Use hex: the password is also part of HALO_DATABASE_URL, where some symbols would break the URL.
    HALO_SECRET_KEY The output of openssl rand -base64 32. Store a copy outside the host, for example in your password manager.
    HALO_ORGANIZATION Your organization's name, shown in the console.

    compose.yml builds HALO_PUBLIC_URL and HALO_DATABASE_URL from these. To have Halo email invite, reset and magic sign-in links, fill in the HALO_SMTP_* variables. Configuration describes every variable.

  4. Download the images and start Halo:

    Bash
    docker compose up -d
    
  5. Check that every service is running:

    Bash
    docker compose ps
    

    postgres and halo-web show healthy once they are ready, and then Caddy starts. If Caddy cannot obtain a certificate, docker compose logs caddy says why; the usual causes are DNS that does not point at the host yet, or ports 80 and 443 blocked by a firewall.

  6. Confirm Halo answers on your domain. The issuer in the response must be https:// followed by your domain:

    Bash
    curl https://auth.example.com/.well-known/openid-configuration
    
  7. Create the first global administrator:

    Bash
    docker compose exec halo-server halo bootstrap --email you@example.com --name "Your Name"
    

    Open the link it prints and create a passkey. The link works once and expires after 7 days. bootstrap refuses to run once a global administrator exists; invite everyone else from the console at https://auth.example.com/admin.

Back up

Run the docker compose commands on the rest of this page from the directory that holds compose.yml: the install directory, such as /opt/halo, or deploy in a checkout of the repository.

Back up two things: the database, and HALO_SECRET_KEY. Signing keys and authenticator-app secrets in the database are encrypted with that key, so a backup restored without the same key cannot sign anyone in. .env holds both the key and the database password.

Create a dump:

Bash
docker compose exec -T postgres pg_dump -U halo -d halo --format=custom > halo-$(date +%F).dump

Copy the dump off the host. To restore it, stop Halo, restore, and start Halo again with the same HALO_SECRET_KEY that was in use when the dump was taken:

Bash
docker compose stop halo-server halo-web
docker compose exec -T postgres pg_restore -U halo -d halo --clean --if-exists < halo-2026-10-04.dump
docker compose start halo-server halo-web

Caddy keeps its certificates in the caddy-data volume. If you lose it, Caddy requests new certificates.

Upgrade

Back up PostgreSQL and HALO_SECRET_KEY first. To roll back after a migration, restore that backup before starting the older version.

The public installer currently uses v0.1.1. To upgrade to v0.2.0, set both Halo image tags in your installed compose.yml to 0.2.0. Run these commands from the installation directory.

Bash
docker compose pull halo-server halo-web
docker compose up -d --no-deps halo-server halo-web

Halo applies database migrations when the new server starts.

Rotate HALO_SECRET_KEY

HALO_SECRET_KEY encrypts the OpenID Connect and SAML signing keys, authenticator-app secrets, the tokens Halo uses to provision applications over SCIM, identity provider client secrets, webhook signing secrets, the SSH certificate authority and email waiting in the outbox. Recovery codes are stored as HMACs keyed from it. Starting Halo with a different key without rotating makes all of that unreadable: /oauth2/keys fails with status 500 and authenticator-app codes stop working. Sessions and passkeys do not depend on the key.

halo rotate-secret-key re-encrypts every stored secret from the current key to a new one in a single transaction, so either everything moves to the new key or nothing changes. Halo must not be running while it does this, or it could write values with the old key afterwards.

  1. Take a backup.

  2. Generate the new key and keep it in your password manager:

    Bash
    openssl rand -base64 32
    
  3. Stop Halo and run the rotation with the new key. HALO_SECRET_KEY still holds the current key from .env:

    Bash
    docker compose stop halo-web halo-server
    docker compose run --rm -e HALO_NEW_SECRET_KEY='<new key>' halo-server rotate-secret-key
    

    The command prints how many values it re-encrypted in each table. If any value cannot be opened with the current key, it stops and changes nothing.

  4. In .env, replace the value of HALO_SECRET_KEY with the new key, then start Halo:

    Bash
    docker compose up -d
    

What the rotation cannot carry over:

  • Recovery codes. Halo only stores an HMAC of each code, so they cannot be re-derived under the new key. The command removes them and lists the people who had them; ask those people to generate new codes on their account's Security page.
  • Opaque access tokens and unredeemed authorization codes. These are encrypted with a key derived from HALO_SECRET_KEY and stop working once Halo runs with the new key. Applications get new access tokens with their refresh tokens, and anyone who was halfway through signing in starts again.

Backups taken before the rotation still need the old key. Keep the old key until those backups have expired.

Treat the key like the database itself: keep it out of version control, back it up with every database backup, and restrict who can read .env.

Health checks

The halo-server image is distroless: it has no shell and no wget or curl, so a health check cannot run inside it. Instead, halo-web runs one against it over the internal network:

Bash
wget -q -O /dev/null http://halo-server:8080/healthz

/healthz returns 200 ok when the database answers and 503 when it does not. Caddy waits for this check before it starts. On v0.2.0, use /readyz on port 8080 to check whether an instance is ready to receive traffic.

Client IP addresses

Halo records the client's IP address on every sign-in, session and audit event. Caddy sets X-Forwarded-For to the client's address and ignores any value the client sent, and halo-web passes the header through unchanged. halo-server reads the header only from addresses in HALO_TRUSTED_PROXIES, and uses the right-most address in it that is not itself a trusted proxy.

HALO_TRUSTED_PROXIES in compose.yml is set to 172.31.250.0/24, the subnet that compose.yml assigns to the halo network. Without it, Halo records the address of the halo-web container for everyone. If that subnet overlaps a network that already exists on your host, docker compose up fails with a "Pool overlaps" error: pick another private /24 and change both places it appears in compose.yml. Configuration describes the variable.

Build the images yourself

To run images built from your checkout instead of the published ones, add compose.build.yml:

Bash
docker compose -f compose.yml -f compose.build.yml up -d --build

To build them without Compose:

Bash
docker build -f deploy/Dockerfile.server -t halo-server .
docker build -f deploy/Dockerfile.web --build-arg HALO_API_URL=http://halo-server:8080 -t halo-web .

halo-web reads HALO_API_URL, the address of halo-server, twice. Next.js writes the forwarding rules for /api, /oauth2, /.well-known, /saml and /scim into the image at build time, so the build argument decides where those requests go. Server-rendered pages read the environment variable at runtime. Set both to the same address. The web container listens on port 3200 on all interfaces (PORT and HOSTNAME).

halo-server listens on HALO_LISTEN, which defaults to :8080. If you change it, change HALO_API_URL and the health check to match.

Use your own reverse proxy

To put Halo behind a proxy you already run, remove the caddy service, publish halo-web on a local port, and forward every path on your domain to it. Your proxy must terminate TLS, and it must set X-Forwarded-For to the client's address after discarding any value the client sent.

Other ways to run Halo

Halo publishes a Helm chart for Kubernetes. Set server.replicaCount to run more than one server. For other orchestrators, use these settings.

  • Use the published images, whose web image forwards to http://halo-server:8080. To use another address for the Go server, build the images yourself and pass that address as HALO_API_URL both when you build the web image and when you run it.
  • Expose only the web interface, behind a proxy that terminates TLS and sets X-Forwarded-For.
  • On the Go server at port 8080, use /healthz for liveness and /readyz for readiness. See Health checks.
  • Give the Go server the variables in Configuration, with HALO_PUBLIC_URL set to the public https address.