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
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_KEYencrypts 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 runhalo rotate-secret-keyas 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,Caddyfileand.env.examplefrom thedeploydirectory 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:
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
-
Point an
Arecord (and anAAAArecord if the host has IPv6) for your domain at the host, and wait until it resolves. -
Create the environment file from a checkout of the repository:
cd deploy cp .env.example .env -
Edit
.envand set these values:Variable Set it to HALO_DOMAINYour domain, for example auth.example.com.POSTGRES_PASSWORDThe output of openssl rand -hex 32. Use hex: the password is also part ofHALO_DATABASE_URL, where some symbols would break the URL.HALO_SECRET_KEYThe output of openssl rand -base64 32. Store a copy outside the host, for example in your password manager.HALO_ORGANIZATIONYour organization's name, shown in the console. compose.ymlbuildsHALO_PUBLIC_URLandHALO_DATABASE_URLfrom these. To have Halo email invite, reset and magic sign-in links, fill in theHALO_SMTP_*variables. Configuration describes every variable. -
Download the images and start Halo:
docker compose up -d -
Check that every service is running:
docker compose pspostgresandhalo-webshowhealthyonce they are ready, and then Caddy starts. If Caddy cannot obtain a certificate,docker compose logs caddysays why; the usual causes are DNS that does not point at the host yet, or ports 80 and 443 blocked by a firewall. -
Confirm Halo answers on your domain. The
issuerin the response must behttps://followed by your domain:curl https://auth.example.com/.well-known/openid-configuration -
Create the first global administrator:
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.
bootstraprefuses to run once a global administrator exists; invite everyone else from the console athttps://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:
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:
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.
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.
-
Take a backup.
-
Generate the new key and keep it in your password manager:
openssl rand -base64 32 -
Stop Halo and run the rotation with the new key.
HALO_SECRET_KEYstill holds the current key from.env:docker compose stop halo-web halo-server docker compose run --rm -e HALO_NEW_SECRET_KEY='<new key>' halo-server rotate-secret-keyThe 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.
-
In
.env, replace the value ofHALO_SECRET_KEYwith the new key, then start Halo: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_KEYand 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:
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:
docker compose -f compose.yml -f compose.build.yml up -d --build
To build them without Compose:
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 asHALO_API_URLboth 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
/healthzfor liveness and/readyzfor readiness. See Health checks. - Give the Go server the variables in Configuration, with
HALO_PUBLIC_URLset to the public https address.