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

```bash
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:

   ```yaml
   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:

```bash
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:

```yaml
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.