KCal/README.md

Kids Calendar

A self-hosted weekly calendar for your family. Parents log in and edit; each child gets a read-only "kiosk" link for a tablet, where they can only tick off tasks that are already there.

• Parents: sign up, invite your spouse, create a calendar per child, edit freely, print, duplicate a calendar for the next week.
• Kids: open their kiosk link on a tablet and add it to the home screen — it launches full-screen with no browser chrome, and they can see the board and check boxes — nothing else.
• Everything a child checks off shows up on the parents' devices within a few seconds, no reload needed — and, if push notifications are set up, as an actual notification too (see below).

Running it

Requires Node.js 22.5+ (for the built-in node:sqlite module — nothing else to compile, no native build tools needed).

npm install
export SESSION_SECRET=$(node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))")
node server.js

Plain node doesn't read .env files — export the variables from .env.example yourself (as above), or use a process manager (pm2, systemd) that does it for you. Docker (below) reads .env automatically. Then open http://localhost:3007/signup.html.

Docker (recommended for a NAS / home server)

cp .env.example .env   # set SESSION_SECRET
docker compose up -d --build

Data lives in a named volume (kids-calendar-data), so it survives container rebuilds. To back it up, back up that volume (or bind-mount ./data:/app/data in docker-compose.yml instead and back up that folder).

Running on Unraid specifically? See UNRAID.md — it uses docker-compose.unraid.yml, which bind-mounts to /mnt/user/appdata/kids-calendar instead of a named volume, matching Unraid's usual appdata convention.

Environment variables

Variable	Default	Notes
SESSION_SECRET	(insecure dev default)	Required. A long random string — see .env.example for how to generate one.
PORT	3007
DATA_DIR	./data	Where the SQLite file lives.
COOKIE_SECURE	false	Set true once this is behind HTTPS (e.g. a reverse proxy with a real certificate), so cookies are marked secure. Leave false for plain-HTTP LAN access, or login cookies won't be sent.
DISABLE_PUBLIC_SIGNUP	false	Set true once your household(s) exist, to stop the /signup.html page from creating new ones. Existing invite links still work.
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY / VAPID_SUBJECT	unset	Optional — enables push notifications. See "Push notifications" below. Leave all three unset to skip the feature entirely; the app degrades gracefully (no broken UI).

Push notifications

When a kid checks off a task on the kiosk, parents can get a real push notification instead of only the silent polling-based update. This is optional — the app works fully without it.

Requires real HTTPS. Not "it's nice to have," a hard platform requirement: Web Push needs a secure context, and iOS Safari specifically requires a browser-trusted certificate (a self-signed one with a click-through warning does not count). http://localhost is a spec-defined exception for local development, but LAN access via http://<ip>:3007 will never get push working on iOS. See "Exposing this beyond your home network" below for your HTTPS options — you need one of those in place first.

Setup, once HTTPS is sorted:

1. Generate a VAPID keypair: npx web-push generate-vapid-keys (or docker run --rm node:22-alpine npx web-push generate-vapid-keys if you don't have Node locally).
2. Set VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, and VAPID_SUBJECT (mailto:you@example.com or an https: URL) in .env, then restart.
3. On the dashboard, each parent clicks "Enable notifications on this device" — this is per-device, so do it on every phone/computer that should get notified.

On iPhone/iPad specifically: Safari only allows push notifications for web apps added to the Home Screen — a regular Safari tab can't subscribe at all. Tap Share → Add to Home Screen on the dashboard first, then open the app icon from your Home Screen and enable notifications from there. The dashboard's notification card explains this in place if it detects it's needed.

Regenerating the VAPID keypair invalidates every existing subscription (everyone would need to re-enable notifications) — treat it as a one-time setup step, not something to rotate casually.

How access works

• Parents have real accounts (email + password) tied to a household. The first person to sign up creates the household; from the dashboard they can generate an invite link (valid 7 days, one-time use) for a spouse to join the same household with their own login.
• Kids never get an account. Each child has an unguessable link (/k/<token>) that shows only their active calendar (set from the dashboard) and lets them toggle checkboxes — the server has no route at all for a kiosk link to edit text, add/delete tasks, or see other children's data. If a tablet is lost, regenerate that child's link from the dashboard to invalidate the old one.

Exposing this beyond your home network

This is built for LAN use by default (plain HTTP, cookies not marked secure). If you want access from outside your home:

• Put it behind a reverse proxy (e.g. Caddy, nginx, Traefik) that terminates HTTPS, then set COOKIE_SECURE=true.
• Set SESSION_SECRET to a real random value (never the dev default).
• Consider setting DISABLE_PUBLIC_SIGNUP=true once your family's household(s) are created.

This same HTTPS setup is also the prerequisite for push notifications (see above) — a real, browser-trusted certificate, not a self-signed one. Options that satisfy this: a domain + Let's Encrypt via the reverse proxy itself, a locally-trusted CA like mkcert with its root profile installed on your devices, or a tunnel (Tailscale Funnel, Cloudflare Tunnel) that terminates real HTTPS for you.