Guide › Self-hosting

Install and self-host

Docker Compose in five minutes, the three environment variables, why a reverse proxy with authentication is not optional, HTTPS for the camera and microphone, updating, and a bare-metal dev run.

Handlr is one container, one volume, no database server. It is meant to live on the box in your closet, on your LAN, behind your own front door.

Requirements

• Docker with Compose (any recent version), on any Linux host — a Raspberry Pi is plenty.
• A reverse proxy that can add authentication and HTTPS (Caddy, Traefik, nginx, Nginx Proxy Manager…), or a private network (Tailscale, NetBird, WireGuard) that already does.
• About 200 MB for the image; storage for your photos and voice memos.

The easy path: the setup wizard

If you would rather not touch a terminal, the Handlr Setup wizard does everything on this page for you — checks Docker, picks a folder, mints the API token, writes the compose file and starts the app. The port it publishes is bound to 127.0.0.1: Handlr opens on that computer only. Opening it to your network is a separate box on the Options page — Let other devices on my network open Handlr — off unless you tick it, and it says in plain words what ticking it means: Handlr has no login, so anyone on your network could open it and download everything in it. A login in front of Handlr (a reverse proxy) does not change that — devices still reach the port directly — so leave it off when the proxy runs on the same computer: it reaches Handlr on 127.0.0.1. Using Tailscale or NetBird? Leave it off too, and once Handlr is installed set HANDLR_BIND in the install folder's .env to the computer's tailnet address (100.x.y.z), then docker compose up -d there: only devices on the tailnet can reach it. After that, open Handlr at http://<tailnet address>:<port> on this computer too — http://localhost:<port> stops answering once it is bound to the tailnet address. Ticked, Handlr listens on 0.0.0.0 — every interface, including any Wi-Fi the computer joins later — so tick it only on a computer that never joins a network you don't trust (every device on every network it joins can open Handlr), or when the proxy runs on another machine and you firewall the port to that machine alone — and on Linux, Docker's published ports bypass host firewalls such as UFW (below). The choice is the HANDLR_BIND line in the .env it writes (127.0.0.1 or 0.0.0.0, or the address you put there; empty or missing means 127.0.0.1), and the last page shows the address for the choice you made. Running the wizard again rewrites .env, so a HANDLR_BIND you set by hand goes back to 127.0.0.1 — set it again. Download it from https://boyslop.dev (macOS, Intel and Apple Silicon), or run installer/setup.sh from the source tree on any machine with Python 3 — no build needed.

Five-minute install

git clone <the repository> handlr && cd handlr
cp .env.example .env
# set HANDLR_API_TOKEN if you want the API; leave it empty to keep the API off
docker compose build --pull
docker compose up -d
curl -s http://127.0.0.1:8770/healthz

/healthz answers with the version, the session state and the loaded modules. The image is built locally from the Dockerfile; there is no registry pull yet (roadmap → releases).

The shipped docker-compose.yml publishes port 8770 on the host, mounts a named volume at /data, runs read-only with a 512 MB limit, and sets TZ/HANDLR_TZ. Change the host port or the timezone to taste.

The environment

More in Customise → instance settings.

Authentication is yours

Two patterns that work:

A. Reverse proxy with forward-auth. Caddy + tinyauth/Authelia/Authentik, Traefik with a forward-auth middleware, nginx with auth_request. Example for Caddy with tinyauth:

handlr.home.example {
    tls internal
    forward_auth tinyauth:3000 {
        uri /api/auth/caddy
        copy_headers Remote-User
    }
    reverse_proxy latch-host:8770
}

Then make sure 8770 is not reachable from anything but the proxy — a firewall rule on the host, or bind the port to the proxy's address only. Note that Docker's published ports bypass host firewalls such as UFW; use DOCKER-USER rules or bind to 127.0.0.1 if the proxy is on the same host.

B. Private network only. If the host is reachable only over Tailscale/NetBird/WireGuard and every device on that network is yours, the network is the login. Publish the port on the host's address on that network, not on every interface: HANDLR_BIND=100.x.y.z with the wizard's compose, or "100.x.y.z:8770:8000" on your own ports line. 0.0.0.0 is every interface — the LAN and any Wi-Fi the machine joins included — so it is not "the private network only". The address must exist when Docker starts Handlr: if Handlr does not come back after a reboot, the tailnet was not up yet — docker compose up -d again. Open it at http://100.x.y.z:8770 on the host itself too: bound there, it no longer answers on localhost. Still terminate HTTPS somewhere, for the next section.

HTTPS is required

Not for privacy — the traffic never leaves your LAN — but because browsers refuse three things on an insecure origin: the microphone (spoken reflections), the camera on some phones, and the share sheet. All three work at https://handlr.your.lan through your proxy and are structurally absent at http://host:8770. A proxy-issued internal certificate (Caddy's tls internal, or your own CA) is fine; install its root on your phone once.

The names it answers to

Handlr answers only to names it has been told about. A web page on someone else's name can point that name at your box (DNS rebinding) and then read whatever your browser can reach — including /export/bundle.zip, which is your whole database. The only thing different about that request is the name in it, so any name that is not yours gets "This box does not answer to that name" and nothing else.

• IP addresses and localhost always work — health checks, curl on the host, the installer, and the way in when nothing else is set up yet.
• Set HANDLR_ALLOWED_HOSTS to the name(s) you use, e.g. handlr.home.example or handlr.home.example,*.tailnet.example. This is the recommended setting.
• Or leave it empty and name the box yourself: open it by its IP address (or localhost), go to Settings → System → answers to, type the name you use and press Answer to this name. Until you do, only IP addresses and localhost reach it. To move to a new name, give the new one (it replaces the old), or press Forget this name — from the IP address, since the old name stops working at once.
• A name is never learnt from a request. Over plain http://, nothing in a request tells an address you typed apart from a rebinding page's own script, so the box never guesses: the name comes from you, on a page a stranger's site can neither load nor post to.
• The setup wizard writes HANDLR_ALLOWED_HOSTS=localhost into .env; add any other name you open it by there.
• Entries are bare names: handlr.home.example, *.home.example, optionally with a port. A URL (https://…), a bare * or a trailing slash never matches; Settings → System lists such entries as ignored.

Handlr also refuses a form sent from another site (a cross-site POST), which is what stops a page you visit from changing your settings behind your back. Scripts and Shortcuts are not affected: they send neither of the headers a browser does, and /api/v1 uses its token.

Behind a reverse proxy

• With Host passed through, put the public name in HANDLR_ALLOWED_HOSTS (or give it on Settings) and everything works.
• With X-Forwarded-Host instead, every value in it is checked like Host, and the rewritten Host has to pass too: list the upstream name as well (HANDLR_ALLOWED_HOSTS=handlr.home.example,handlr) unless it is an IP address.
• Without either, a form from your own page still works when its origin is an exact name in HANDLR_ALLOWED_HOSTS (and Handlr logs a warning that the proxy is rewriting Host), but a browser that sends Origin: null is refused, and the rebinding read above stays open.

Updating

git pull
docker compose build --pull
docker compose up -d
curl -s http://127.0.0.1:8770/healthz     # the version must read back as the one you built

docker compose pull does nothing here — the image is local. Read the version off /healthz rather than trusting the exit code. The changelog is CHANGELOG.md; schema migrations run on start and are recorded in the database.

If you keep a rollback: docker tag aurora/handlr:local aurora/handlr:rollback-$(date +%F) before the build.

Backups

One volume: the database (WAL mode) and media/. See Export and backup for a WAL-safe copy and the watermark that proves it.

Running on a workstation (development)

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt pytest httpx
./run-dev.sh              # http://127.0.0.1:8770, data in ./.data, API token "dev-token"
.venv/bin/pytest -q       # the test suite, including the privacy and settings-split guards

.data/ is throwaway and gitignored. The dev server and a container share nothing.

A worked example

The reference deployment runs on a Proxmox VM behind Caddy (tls internal, tinyauth → passkeys), with the raw port firewalled to the proxy host and to the private mesh, a keyword health monitor on /healthz, a nightly WAL-safe database dump, and the whole VM in two backup layers. None of that is required; all of it is the shape the privacy page describes.

This page is docs/install.md in the repo. Spotted a mistake? Tell us how to report it →