HealthLog/docs/self-hosting/unraid.md

HealthLog on Unraid

HealthLog runs on Unraid in two ways. The Compose Manager path is the clean, self-contained install (app + database as one unit) and is recommended. The Community Applications (CA) template gives you the familiar one-app-at-a-time Unraid UI, but because CA templates describe a single container you install PostgreSQL separately and wire the two together.

HealthLog stores all persistent state in PostgreSQL — the app container itself is stateless (the offline geo-IP databases are either baked in at build time or mounted read-only; replaceable either way, not state). A backup of the database is a backup of everything.

What you need

• Unraid 6.12 or newer.
• The image: ghcr.io/mbombeck/healthlog:latest (multi-arch, amd64 + arm64).
• Three secrets, each generated with openssl rand -hex 32 (a 64-character hex string). On Unraid open the terminal (the >_ icon, top-right) and run the command three times:
  • POSTGRES_PASSWORD — the database password
  • ENCRYPTION_KEY — AES-256-GCM key for data at rest
  • API_TOKEN_HMAC_KEY — API token hashing key

Keep ENCRYPTION_KEY safe and backed up. If you lose it, the encrypted columns become unrecoverable.

---

Recommended: Compose Manager

This installs the app and its database together, exactly as the project's docker-compose.yml describes.

1. Install Compose Manager from Community Applications (search "Compose Manager", by dcflachs).

2. Settings → Docker → Compose Manager → Add New Stack, name it healthlog.

3. Paste the project docker-compose.yml into the stack's compose file.

4. Edit the stack's .env (the "Edit Stack → env" field) and set:

   POSTGRES_PASSWORD=<your openssl rand -hex 32>
   ENCRYPTION_KEY=<your openssl rand -hex 32>
   API_TOKEN_HMAC_KEY=<your openssl rand -hex 32>
   SESSION_COOKIE_SECURE=false
   NEXT_PUBLIC_APP_URL=http://tower:3000
   APP_URL=http://tower:3000
   

   Replace tower with your server's hostname or IP. SESSION_COOKIE_SECURE=false is required for plain-HTTP LAN access — see the note below.

5. Compose Up. The app waits for PostgreSQL, runs database migrations on first boot, then starts serving.

6. Open http://tower:3000. The first account you register becomes the admin.

Verify the running version:

curl -s http://tower:3000/api/version

---

Alternative: Community Applications template

Use this if you prefer the per-app Unraid UI. You install PostgreSQL yourself, then add HealthLog pointed at it.

Step 1 — install PostgreSQL

1. In Apps (Community Applications), search for a PostgreSQL container (for example jj9987's postgresql). Install version 18; an existing 16 works too. Moving a 16 to 18 later is a dump and restore, see Moving to a newer Postgres major.
2. Set:
   • POSTGRES_USER = healthlog
   • POSTGRES_PASSWORD = your generated password
   • POSTGRES_DB = healthlog
3. Map the Postgres data path to a share on the array (e.g. /mnt/user/appdata/healthlog-db) so the database survives container updates.
4. Note the container's IP (or container name if both run on the same custom Docker network).

Step 2 — add the HealthLog template

The template lives at docs/self-hosting/unraid/healthlog.xml. Add it via Docker → Add Container → Template and paste the raw URL, or copy it into /boot/config/plugins/dockerMan/templates-user/ and pick it from the template dropdown.

Fill in the fields:

Field	Value
WebUI Port	3000
DATABASE_URL	postgresql://healthlog:<password>@<postgres-host>:5432/healthlog?schema=public
ENCRYPTION_KEY	your generated key
API_TOKEN_HMAC_KEY	your generated key
SESSION_COOKIE_SECURE	false for plain-HTTP LAN access
NEXT_PUBLIC_APP_URL	http://tower:3000 (or your domain)
APP_URL	same as NEXT_PUBLIC_APP_URL

Replace <password> and <postgres-host> with the values from Step 1. Apply, then open http://tower:3000 — the first registered user becomes the admin.

The HealthLog container has no persistent volume of its own; all state is in the PostgreSQL container you installed in Step 1. Back that one up.

---

The one setting that trips people up

SESSION_COOKIE_SECURE=false is required for plain-HTTP LAN installs (http://tower:3000). Left at its default, the session cookie carries the Secure flag, the browser refuses to send it over HTTP, and login appears to "do nothing" — the page reloads to the login screen with no error.

Set SESSION_COOKIE_SECURE=true (or leave it unset) only when a TLS reverse proxy serves HealthLog over HTTPS. In that case also point NEXT_PUBLIC_APP_URL and APP_URL at the public https:// URL.

Save the recovery kit

Copy ENCRYPTION_KEY, API_TOKEN_HMAC_KEY and, with off-host copies, BACKUP_ENCRYPTION_KEY from the template into your password manager, then confirm the recovery kit under Admin, Encryption (set HEALTHLOG_PLATFORM=unraid so the kit opens on the Unraid instructions). A reinstall with a new key over the old database makes the data unreadable; HealthLog then refuses to serve and says so. See Getting started.

Updates

Pin a release tag (ghcr.io/mbombeck/healthlog:vX.Y.Z) and bump deliberately, or track :latest and let Unraid's update check re-pull. Skim the CHANGELOG before upgrading, and back up the database first. Migrations are forward-only and run automatically on container start.

Health check

Both /api/health and /api/version respond without authentication. /api/health returns 200 when the database and background worker are up (503 otherwise) and is the container health probe baked into the image. /api/version returns the version, build SHA, and build timestamp for deploy verification.