brianpooe/homelab-blueprint
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
homelab-blueprint/docker-compose-files/koffan/README.md
Brian Pooe 3a314b16d6 feat: add Koffan, Rackula, and SnapOtter stacks; expose Hermes dashboard 
- new compose templates + READMEs for the three LXC apps (110-112)
- Makefile deploy targets (rackula pre-owns its data dir for uid 1001)
- Caddy vhosts for all four, incl. Hermes /auth/login redirect workaround
- firewall docs: CADDY->TRUSTED rules for LXCs 110-113
2026-07-06 20:50:34 +02:00

1.9 KiB
Raw Blame History

Koffan

Ultra-lightweight (~16 MB, SQLite) shared grocery/shopping list for the household. Real-time sync between devices; no per-user accounts — everyone shares a single password set via KOFFAN_APP_PASSWORD.

Persistent Data

The koffan_data named volume holds the SQLite database (/data/shopping.db). Small enough that a docker compose cp or volume backup covers it.

Installation

  1. Create .env if it does not exist:

    cp -n .env.sample .env

  2. Adjust the values in .env — at minimum set a real password:

    TZ=Africa/Johannesburg
KOFFAN_PORT=8080
KOFFAN_APP_PASSWORD=<pick-something>

DOCKERLOGGING_MAXFILE=3
DOCKERLOGGING_MAXSIZE=10m

  3. Deploy with make:

    make deploy-koffan

    Manual equivalent:

    ./substitute_env.sh docker-compose-files/koffan/template.yaml docker-compose.koffan.yml .env
docker compose -f docker-compose.koffan.yml config --quiet
docker compose -f docker-compose.koffan.yml up -d

  4. Verify the container and open http://<host-ip>:8080:

    docker compose -f docker-compose.koffan.yml ps
docker compose -f docker-compose.koffan.yml logs --tail=100 koffan

Reverse Proxy

The Caddyfile proxies koffan.<domain> to this host on port 8080. After changing the port, update docker-compose-files/caddy/Caddyfile_template and run make reload-caddy.

Notes

  • Login is rate-limited (5 attempts / 15 min, 30 min lockout) by default.
  • KOFFAN_DISABLE_AUTH=true removes the login entirely — anyone who can reach the app (via Caddy from TRUSTED/FAMILY/MEDIA) can edit the list.
  • Set API_TOKEN in the environment to enable the REST API (disabled otherwise).

Useful Commands

# Tail logs
docker compose -f docker-compose.koffan.yml logs -f koffan

# Recreate after an image update
docker compose -f docker-compose.koffan.yml pull
docker compose -f docker-compose.koffan.yml up -d