KCal/UNRAID.md

Running on Unraid

This app has no native/compiled dependencies (it uses Node's built-in node:sqlite), so it builds and runs on Unraid's stock Docker exactly like anywhere else. docker-compose.unraid.yml builds straight from the Gitea repo — Docker/BuildKit clones it itself as part of the build, so you don't need to check out the source on the array at all, and there's no deploy key involved in this path.

1. Make the repo readable over HTTP

The compose file's build.context is a Git URL (https://git.oservr.com/ort/KCal.git#main) — Docker fetches that itself at build time. This is a read-only clone, same as any anonymous git clone, so the repo needs to allow anonymous HTTP read access:

In Gitea: repo → Settings → Visibility → Public (save).

No token, no key, no extra permission grant — public visibility is sufficient for a read-only clone.

2. Create the appdata data folder

mkdir -p /mnt/user/appdata/kids-calendar

This is where the SQLite database will live — the compose file bind-mounts it in, instead of using a Docker-managed named volume, so it shows up normally in Unraid's Docker tab and gets picked up by appdata backup plugins (e.g. CA Backup/Restore) like any other app's data.

3. Deploy

Via Compose Manager Plus (recommended)

1. Docker → Compose → Add Stack, name it kids-calendar.

2. In the Compose tab, paste:

   services:
     kids-calendar:
       build:
         context: https://git.oservr.com/ort/KCal.git#main
         dockerfile: Dockerfile
       container_name: kids-calendar
       ports:
         - "3007:3007"
       volumes:
         - /mnt/user/appdata/kids-calendar:/app/data
       environment:
         - SESSION_SECRET=${SESSION_SECRET:?set a long random value in .env}
         - COOKIE_SECURE=${COOKIE_SECURE:-false}
         - DISABLE_PUBLIC_SIGNUP=${DISABLE_PUBLIC_SIGNUP:-false}
       restart: unless-stopped
   

3. In the ENV tab, set:

   SESSION_SECRET=<output of: openssl rand -hex 32>
   COOKIE_SECURE=false
   DISABLE_PUBLIC_SIGNUP=false
   

4. Compose Up. First run builds the image (a minute or so — it's cloning the repo and running npm install), then the container starts on port 3007.

Via terminal (no plugin needed)

You only need the one compose file and a .env next to it — not a full checkout, since Docker fetches the source itself:

mkdir -p /mnt/user/appdata/kids-calendar-src
cd /mnt/user/appdata/kids-calendar-src
curl -o docker-compose.unraid.yml \
  https://git.oservr.com/ort/KCal/raw/branch/main/docker-compose.unraid.yml
cat > .env <<EOF
SESSION_SECRET=$(openssl rand -hex 32)
COOKIE_SECURE=false
DISABLE_PUBLIC_SIGNUP=false
EOF
docker compose -f docker-compose.unraid.yml up -d --build

4. Use it

Open http://<unraid-ip>:3007/signup.html, create the first parent account, invite your spouse, add your kids, build out calendars, and grab each child's kiosk link from the dashboard for their tablet.

Updating

Docker re-clones the repo's main branch fresh every time you build — there's no separate git pull step. Just re-run the build:

• Compose Manager Plus: right-click the stack → Update & Rebuild (or Build & Up if stopped).
• Terminal: docker compose -f docker-compose.unraid.yml up -d --build from the folder in the terminal steps above.

Either way, your data in /mnt/user/appdata/kids-calendar is untouched.

Prefer not to make the repo public?

If you'd rather keep KCal private, the alternative is authenticating the git-context fetch with a Gitea access token instead of flipping visibility — generate a read-only token in Gitea, then reference it via compose variable substitution so it isn't hardcoded in the file itself:

build:
  context: https://${GITEA_USER}:${GITEA_TOKEN}@git.oservr.com/ort/KCal.git#main

with GITEA_USER/GITEA_TOKEN set in the stack's ENV tab (or .env for the terminal path) instead of SESSION_SECRET's neighbors above. Ask if you want this wired up instead.

Reverse proxy / access from outside your LAN

If you're exposing this beyond your home network (e.g. via Swag or Nginx Proxy Manager, both common on Unraid) with a real HTTPS certificate:

• Point the proxy at http://<unraid-ip>:3007 internally.
• Set COOKIE_SECURE=true (ENV tab, or .env for the terminal path) and rebuild — otherwise login cookies won't be marked secure and some browsers/proxies will refuse to send them back over HTTPS.
• Once your household(s) exist, consider setting DISABLE_PUBLIC_SIGNUP=true so /signup.html stops accepting new households.

Backups

Since data lives at /mnt/user/appdata/kids-calendar (a plain file, the SQLite database), it's covered by whatever you already use to back up /mnt/user/appdata — no special-casing needed.