docs(self-hosting): add Unraid CA and Portainer templates, harden compose quick-start

Surface the load-bearing first-run vars in docker-compose.yml and the README
quick-start: secret generation, the SESSION_COOKIE_SECURE=false LAN note, the
single persistent volume, and a /api/version verify step. Add an Unraid
Community Applications template plus a NAS walkthrough covering the external
Postgres setup, and a Portainer app template referencing the compose stack.
This commit is contained in:
Marc-André Bombeck committed 2026-06-21 10:32:40 +02:00
1 parent 3712b80d0f
commit c903c7f1b1
6 files changed
+358 -8

No files matched your search

+34 -6
View File
@@ -1,3 +1,22 @@
# HealthLog — two-container stack (app + Postgres 16).
#
# First run (clean host):
# cp .env.example .env
# echo "POSTGRES_PASSWORD=$(openssl rand -hex 32)" >> .env
# echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env
# echo "API_TOKEN_HMAC_KEY=$(openssl rand -hex 32)" >> .env
# docker compose up -d
# # then open http://<host>:3000 — the first registered user becomes admin.
#
# LAN / plain-HTTP self-hosts (NAS, homelab, Tailscale): set
# SESSION_COOKIE_SECURE=false
# in .env, otherwise the session cookie carries the `Secure` flag over HTTP
# and login silently fails. This is the single most common self-host snag.
# Leave it unset (or true) only when a TLS reverse proxy serves HTTPS.
#
# Persistent state lives in exactly one named volume (`pgdata`, Postgres'
# data dir). The app container is stateless — GeoLite2 MMDBs are baked into
# the image — so a backup of the database is a backup of everything.
services:
# Single-container default (HEALTHLOG_PROCESS_TYPE=all). Existing
# self-host deployments stay working with `docker compose up`.
@@ -39,18 +58,27 @@ services:
# a free connection before erroring.
DATABASE_URL: "postgresql://healthlog:${POSTGRES_PASSWORD}@db:5432/healthlog?schema=public&connection_limit=${DB_CONNECTION_LIMIT:-20}&pool_timeout=${DB_POOL_TIMEOUT:-20}"
NODE_ENV: production
# Encryption at rest (AES-256-GCM). Generate each secret with
# `openssl rand -hex 32` (a 64-char hex string = 32 bytes). ENCRYPTION_KEY
# is the single-key path and is all most self-hosts need. The map form
# (ENCRYPTION_KEYS={"v1":"<hex>","v2":"<hex>"} + ENCRYPTION_ACTIVE_KEY_ID=v2)
# is for key rotation — see docs/ops/encryption-key-rotation.md. Keep these
# values stable and backed up: lose them and the encrypted columns are
# unrecoverable.
ENCRYPTION_KEY: "${ENCRYPTION_KEY}"
ENCRYPTION_KEYS: "${ENCRYPTION_KEYS:-}"
ENCRYPTION_ACTIVE_KEY_ID: "${ENCRYPTION_ACTIVE_KEY_ID:-}"
API_TOKEN_HMAC_KEY: "${API_TOKEN_HMAC_KEY}"
NEXT_PUBLIC_APP_URL: "${NEXT_PUBLIC_APP_URL:-http://localhost:3000}"
APP_URL: "${APP_URL:-http://localhost:3000}"
# v1.5.1 session-cookie Secure-flag opt-out. Forwarded explicitly so
# an operator setting SESSION_COOKIE_SECURE=false in .env actually
# reaches the Node process (the compose `environment:` block is a
# whitelist — vars not listed here don't propagate from .env into
# the container, even though docker-compose reads .env for
# `${VAR}` substitution at compose-up time).
# Session-cookie Secure-flag opt-out. SET THIS TO false FOR LAN / plain-HTTP
# self-hosts (http://<host>:3000 with no TLS reverse proxy) — otherwise the
# session cookie carries the `Secure` flag, the browser drops it over HTTP,
# and login silently fails. Unset → the flag tracks NODE_ENV=production
# (i.e. on); set to true to force it. Forwarded explicitly so an operator
# value in .env reaches the Node process (the `environment:` block is a
# whitelist — vars not listed here don't propagate even though
# docker-compose reads .env for `${VAR}` substitution at compose-up time).
SESSION_COOKIE_SECURE: "${SESSION_COOKIE_SECURE:-}"
# v1.18.11 (W3) — client-IP resolution + geo lookup. Behind Cloudflare
# the real visitor IP is in `cf-connecting-ip`; set