From 9021a7839d8d976393b56429a01de03a221024b2 Mon Sep 17 00:00:00 2001 From: ort Date: Sat, 15 Aug 2026 14:50:00 -0400 Subject: [PATCH] Build Unraid image directly from the Gitea repo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docker-compose.unraid.yml now uses a Git URL as the build context (https://git.oservr.com/ort/KCal.git#main) instead of requiring a manual clone onto the array — Docker/BuildKit fetches the source itself at build time. Requires the repo to allow anonymous HTTP read access in Gitea (Settings -> Visibility -> Public); this is a read-only clone, nothing more. Verified with a real docker build/compose run against the public repo, not just syntax-checked. UNRAID.md rewritten to match: no deploy key, no NerdTools/git, no source checkout needed. Kept a token-auth alternative documented for anyone who'd rather keep the repo private. --- UNRAID.md | 172 +++++++++++++++++++------------------- docker-compose.unraid.yml | 9 +- 2 files changed, 93 insertions(+), 88 deletions(-) diff --git a/UNRAID.md b/UNRAID.md index 729379b..2f32ee5 100644 --- a/UNRAID.md +++ b/UNRAID.md @@ -2,105 +2,88 @@ 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. This file covers the Unraid-specific parts: getting the -code onto the array, where data lives, and how to run it via either the -Compose Manager plugin or the terminal. +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. Get the code onto Unraid +## 1. Make the repo readable over HTTP -Pick whichever is easier for you — both end up with the project folder -somewhere under `/mnt/user/`. +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: -**Option A — copy via network share (no git needed on Unraid):** -Unraid shares `/mnt/user/appdata` over SMB by default. From your Mac: +In Gitea: **repo → Settings → Visibility → Public** (save). -```bash -mkdir -p /Volumes/appdata/kids-calendar-src # after connecting to \\TOWER\appdata -rsync -av --exclude node_modules --exclude data --exclude .git \ - "/Users/ort84/kids calendar/kids-calendar/" /Volumes/appdata/kids-calendar-src/ -``` +No token, no key, no extra permission grant — public visibility is +sufficient for a read-only clone. -(Connect to the share first via Finder → Go → Connect to Server → -`smb://TOWER/appdata`, adjust the mount path/share name to match your -server.) - -**Option B — git clone directly on Unraid:** -Unraid's base OS doesn't ship git. Install the **NerdTools** plugin from -Community Applications, enable `git` in it, then from the Unraid terminal -(Tools → Terminal, or SSH in): - -```bash -mkdir -p /mnt/user/appdata/kids-calendar-src -cd /mnt/user/appdata/kids-calendar-src -git clone ssh://git@git.oservr.com:23/ort/KCal.git . -``` - -This needs the deploy key available on Unraid too (copy `GitOServr/` over -via the same SMB share, then `chmod 600` the private key file — SSH will -refuse a world-readable key just like it did on the Mac). Only do this if -you're comfortable having a copy of that key on the server; Option A avoids -that entirely. - -## 2. Create the appdata folder +## 2. Create the appdata data folder ```bash mkdir -p /mnt/user/appdata/kids-calendar ``` -This is where the SQLite database will live — `docker-compose.unraid.yml` +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. Set up `.env` +## 3. Deploy -In the project folder on Unraid (`kids-calendar-src` from step 1): - -```bash -cp .env.example .env -``` - -Edit `.env` and set: - -``` -SESSION_SECRET= -``` - -Generate one with: - -```bash -openssl rand -hex 32 -``` - -(Unraid ships `openssl`. If for some reason it's not available, `docker -run --rm node:22-alpine node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"` -works too.) - -Leave `COOKIE_SECURE=false` unless you're putting this behind HTTPS (see -"Reverse proxy" below). - -## 4. Run it - -**Via the Compose Manager plugin (recommended):** install "Docker Compose -Manager" from Community Applications, add a new stack pointing at the -`kids-calendar-src` folder, and have it use `docker-compose.unraid.yml` -(the plugin lets you pick which compose file in the folder to use — if it -only supports a file literally named `docker-compose.yml`, either rename -`docker-compose.unraid.yml` to that inside your Unraid copy, or symlink -it: `ln -s docker-compose.unraid.yml docker-compose.yml`). Start the -stack from the plugin's UI. - -**Via terminal:** +### 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= + 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 <:3007/signup.html`, create the first parent account, invite your spouse, add your kids, build out calendars, and grab @@ -108,15 +91,30 @@ each child's kiosk link from the dashboard for their tablet. ## Updating -After pulling/copying new code: +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: -```bash -cd /mnt/user/appdata/kids-calendar-src -docker compose -f docker-compose.unraid.yml up -d --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 ``` - -This rebuilds the image and recreates the container; your data in -`/mnt/user/appdata/kids-calendar` is untouched. +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 @@ -124,8 +122,8 @@ 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://:3007` internally. -- Set `COOKIE_SECURE=true` in `.env` and re-run the `up -d --build` command - above — otherwise login cookies won't be marked secure and some +- 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 diff --git a/docker-compose.unraid.yml b/docker-compose.unraid.yml index 971ebcd..ca00653 100644 --- a/docker-compose.unraid.yml +++ b/docker-compose.unraid.yml @@ -1,6 +1,13 @@ services: kids-calendar: - build: . + build: + # Docker/BuildKit clones the repo itself at build time — no manual + # git clone onto the array needed. Requires the repo to allow + # anonymous HTTP read access in Gitea (Settings → Visibility → + # Public); this is a read-only clone, so nothing beyond that is + # needed. #main is the branch to build from. + context: https://git.oservr.com/ort/KCal.git#main + dockerfile: Dockerfile container_name: kids-calendar ports: - "3007:3007"