From 3046e46d1c4f8a145e929d7c33c11576ac0f5f70 Mon Sep 17 00:00:00 2001 From: Elijah Date: Thu, 12 Nov 2026 11:29:22 -0700 Subject: [PATCH] Add V2 Forgejo workflow publishing study:v2 image Pushes to v2 typecheck and test inside the Node 24 image via a new Dockerfile test stage, build and smoke-test the production image as a fresh non-root container, then publish :v2 and :v2-. Never touches V1's :latest. Document the image tags and Unraid 99:100 volume ownership. Co-Authored-By: Claude Opus 5.5 --- .forgejo/workflows/build-v2.yml | 68 +++++++++++++++++++++++++++++++++ Dockerfile | 9 ++++- README.md | 5 ++- docs/DEPLOYMENT.md | 35 +++++++++++++---- 4 files changed, 107 insertions(+), 10 deletions(-) create mode 100644 .forgejo/workflows/build-v2.yml diff --git a/.forgejo/workflows/build-v2.yml b/.forgejo/workflows/build-v2.yml new file mode 100644 index 0000000..2941eb8 --- /dev/null +++ b/.forgejo/workflows/build-v2.yml @@ -0,0 +1,68 @@ +name: Verify and publish V2 container + +# Publishes ONLY the `v2` and `v2-` tags. It never touches `latest`, which V1's +# workflow on `main` publishes and the current production container may track. +on: + push: + branches: + - v2 + workflow_dispatch: + +jobs: + build-and-push: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Resolve image names + run: | + IMAGE_PATH=$(echo "git.elijahkuntz.com/${{ gitea.actor }}/${{ github.event.repository.name }}" | tr '[:upper:]' '[:lower:]') + SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-12) + echo "IMAGE_PATH=$IMAGE_PATH" >> "$GITHUB_ENV" + echo "IMAGE_SHA=$IMAGE_PATH:v2-$SHORT_SHA" >> "$GITHUB_ENV" + echo "IMAGE_V2=$IMAGE_PATH:v2" >> "$GITHUB_ENV" + + # Typecheck and tests run inside the Node 24 image the runtime uses, so the runner's + # own Node version does not matter. + - name: Typecheck and test + run: docker build --target test -t "study-v2-test:${{ github.sha }}" . + + - name: Build production image + run: docker build -t "$IMAGE_SHA" . + + - name: Smoke-test the production image + run: | + SMOKE="study-v2-smoke-$(openssl rand -hex 6)" + cleanup() { docker rm -f "$SMOKE" > /dev/null 2>&1 || true; } + trap cleanup EXIT + docker run -d --name "$SMOKE" "$IMAGE_SHA" + for attempt in $(seq 1 30); do + STATUS=$(docker inspect --format='{{.State.Health.Status}}' "$SMOKE") + if [ "$STATUS" = "healthy" ]; then break; fi + if [ "$(docker inspect --format='{{.State.Running}}' "$SMOKE")" != "true" ]; then break; fi + sleep 2 + done + if [ "$(docker inspect --format='{{.State.Health.Status}}' "$SMOKE")" != "healthy" ]; then + docker logs "$SMOKE" + exit 1 + fi + # Runs as the non-root node user, data volume writable, first-run setup code created. + test "$(docker exec "$SMOKE" id -u)" != "0" + docker exec "$SMOKE" test -s /data/setup-code.txt + docker exec "$SMOKE" test -s /data/study.db + # Web app served; fresh install reports setup needed; private API denied. + docker exec "$SMOKE" node -e "fetch('http://127.0.0.1:3726/').then(async r => { const t = await r.text(); if (!r.ok || !t.includes('id=\"root\"')) process.exit(1) }).catch(() => process.exit(1))" + docker exec "$SMOKE" node -e "fetch('http://127.0.0.1:3726/api/auth/status').then(async r => { const b = await r.json(); if (!r.ok || b.configured !== false || b.authenticated !== false) process.exit(1) }).catch(() => process.exit(1))" + docker exec "$SMOKE" node -e "fetch('http://127.0.0.1:3726/api/classes').then(r => { if (r.status !== 401) process.exit(1) }).catch(() => process.exit(1))" + docker logs "$SMOKE" 2>&1 | grep -vi 'setup code' | tail -n 20 + + - name: Log into registry + run: | + echo "${{ secrets.FORGEJO_PAT }}" | docker login git.elijahkuntz.com -u "${{ gitea.actor }}" --password-stdin + + - name: Publish v2 tags + run: | + docker tag "$IMAGE_SHA" "$IMAGE_V2" + docker push "$IMAGE_SHA" + docker push "$IMAGE_V2" diff --git a/Dockerfile b/Dockerfile index 4fda957..3e5847a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,9 +1,16 @@ # syntax=docker/dockerfile:1 -FROM node:24-bookworm-slim AS build +FROM node:24-bookworm-slim AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . + +# CI target: `docker build --target test .` runs typecheck and the full test suite on the +# same Node version the runtime image uses. Not part of the default image build. +FROM deps AS test +RUN npm run typecheck && npm test + +FROM deps AS build RUN npm run build && npm prune --omit=dev FROM node:24-bookworm-slim AS runtime diff --git a/README.md b/README.md index c5c9c8f..d0e41a3 100644 --- a/README.md +++ b/README.md @@ -78,5 +78,6 @@ account-specific model access, Linux container behavior and Unraid proxy configu be checked in their target environments. [PROGRESS.md](PROGRESS.md) records completed work, remaining verification, decisions and the -resume procedure. V1 remains on `main` and in Git history; all V2 work is on local `v2`. -Nothing is automatically pushed or published. +resume procedure. V1 remains on `main` and in Git history; V2 work is on the `v2` branch. +Pushing `v2` to Forgejo runs CI and publishes the `study:v2` image (never `:latest`); see +[deployment](docs/DEPLOYMENT.md). Nothing deploys automatically. diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 2e3854e..d298811 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -2,8 +2,25 @@ ## Unraid -Build from this checkout with `docker build -t study-desk:v2-local .`. -Create a **new** container named `study-v2`, image `study-desk:v2-local`: +### Getting the image + +Every push to the `v2` branch runs `.forgejo/workflows/build-v2.yml`. It typechecks and runs the +test suite inside the Node 24 image (`docker build --target test`), builds the production image, +smoke-tests it as a fresh non-root container, then publishes two tags: + +- `git.elijahkuntz.com/elijah/study:v2` (moves with each successful `v2` push) +- `git.elijahkuntz.com/elijah/study:v2-<12-char commit>` (fixed; use it to pin or roll back) + +It **never** publishes `:latest`, which V1's `main` workflow owns. Keep the V1 container on its +existing tag. Do not merge `v2` into `main` until V2 replaces V1: that merge would remove V1's +workflow, and this one only triggers on `v2`. The workflow can also be run manually. + +Alternatively build locally from this checkout with `docker build -t study-desk:v2-local .`. + +### Container settings + +Create a **new** container named `study-v2`, image `git.elijahkuntz.com/elijah/study:v2` +(or your local tag): | Setting | Value | | --- | --- | @@ -16,11 +33,15 @@ Create a **new** container named `study-v2`, image `study-desk:v2-local`: | TRUST_PROXY | true only behind a trusted proxy | | COOKIE_SECURE | true with HTTPS; auto for local HTTP testing | -The image uses UID/GID **1000:1000**. Create a dedicated host directory writable by that user -before starting. For example, on Unraid: `mkdir -p /mnt/user/appdata/study-v2` then -`chown 1000:1000 /mnt/user/appdata/study-v2`. Only change permissions on this new folder. -Alternatively select an appropriate non-root UID/GID using Docker's `--user` option and grant -that identity access to the dedicated directory. Never mount V1's database or data folder. +The image uses UID/GID **1000:1000**. Unraid appdata folders are normally owned by +`nobody:users` (**99:100**), which that user cannot write to. Pick one: + +- Create the dedicated folder and hand it to 1000: `mkdir -p /mnt/user/appdata/study-v2` then + `chown 1000:1000 /mnt/user/appdata/study-v2`. Only change permissions on this new folder. +- Or keep Unraid's ownership and add `--user 99:100` to the container's Extra Parameters. + +If the container restarts repeatedly with a permissions error in its log, this is the cause. +Never mount V1's database or data folder. The supplied `compose.yaml` defaults to `./data-v2` and host port 3727. Override `STUDY_DATA_DIR` for Unraid. Do not reuse a V1 container name, mount or proxy destination.