Install with Docker Compose

HouseCairn ships as a single container image, ghcr.io/housecairn/housecairn, for linux/amd64 and linux/arm64. It holds the web server, the background task worker and the static files. Everything it writes goes to one volume, /data. The design decisions behind the image are in ADR 0015.

Requirements

  • Docker Engine 25.0 or later, with the Compose plugin (docker compose) 2.24.0 or later.

    • Engine 25.0: the image’s health check checks every 2 seconds while the container starts (--start-interval), an option that requires Docker Engine 25.0 or later (release notes).

    • Compose 2.24.0: the example compose.yaml marks deploy/postgres.env as optional (required: false), which Compose supports since 2.24.0.

    • Check with docker version --format '{{.Server.Version}}' and docker compose version.

  • A reverse proxy that terminates HTTPS in front of HouseCairn (Caddy, Traefik, nginx…). HouseCairn listens on plain HTTP, port 8000, and redirects every request to HTTPS; it expects the proxy to set X-Forwarded-Proto. See Reverse proxy.

Install

  1. Get compose.yaml and deploy/production.env.example from the repository, in the same layout:

    mkdir -p housecairn/deploy && cd housecairn
curl -fsSLO https://raw.githubusercontent.com/HouseCairn/housecairn/main/compose.yaml
curl -fsSL -o deploy/production.env \
  https://raw.githubusercontent.com/HouseCairn/housecairn/main/deploy/production.env.example

  2. Edit deploy/production.env: set ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS to your host name (see Environment variables). Leave SECRET_KEY empty: a key is generated on first start. HOUSECAIRN_FORWARDED_ALLOW_IPS names the reverse proxy whose headers HouseCairn trusts: keep 192.0.2.1 for a proxy on this host, the gateway of the network fixed in compose.yaml.

  3. In compose.yaml, replace the edge tag with a released version, ideally with its digest (ghcr.io/housecairn/housecairn:X.Y.Z@sha256:...). Verify the image before the first start.

  4. Start it, then check its state:

    docker compose up -d
docker compose ps          # STATUS shows "healthy" after a few seconds
docker compose logs -f housecairn

  5. Point your reverse proxy at http://127.0.0.1:8000. To run the proxy itself in Compose (Caddy or Traefik), see the example in Reverse proxy, which also gives the value of HOUSECAIRN_FORWARDED_ALLOW_IPS for each case.

On every start, the container creates the secret key if it is missing, applies the database migrations, then starts the web server (gunicorn, two processes by default) and the task worker (django-q2). If either stops, the container stops, and Compose restarts it.

Next: create the first administrator.

Edit this page on GitHub Report a problem with this page