From bfc5135f1927da2946655e3a8c9efb8e3974ec26 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Thu, 27 Aug 2026 07:39:49 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20true=20up=20README=20=E2=80=94=20status?= =?UTF-8?q?,=20the=20five=20pieces,=20CI=20(#3070)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md was last touched in 4aff9c5 (2026-05-14) and several of its most visible lines had gone false: - "Pre-v1. Not yet functional." — FC has been continuously deployed for months. Replaced with what main/dev actually mean for what's running. - "Node 22 pre-installed" — ci-requirements.md and extension.yml both say node 24, and frontend/package.json requires >=24. - "Runner label python-ci — a runner with Python 3.14, ruff and Node 22 pre-installed ... The runner image (runner-base:python-ci) is built from CI-Runner/CI-python/" — describes runs-on as selecting the toolchain. It doesn't: runs-on is a scheduling label, and every job names its own container.image (ci-python:3.14, or node:24-bookworm-slim for the extension lane). - "Both ci.yml and build.yml use this label" — there are three workflows. The CI section now points at ci-requirements.md rather than restating it, so the two can't drift apart again; that file is current and is the one the CI-runner process expects. Added a "What's in here" table for the five deployable pieces — the extension, the GPU agent and the ML image were unmentioned, three of the five. Also corrected the RELEASE_TOKEN write:release scope, which is no longer "for future release-cutting workflows": it backs the ext- releases that cache the signed XPI. Refs #3070 --- README.md | 41 +++++++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 225f318..c13f2f6 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,21 @@ Combines what was [ImageRepo](https://git.fabledsword.com/bvandeusen/ImageRepo) ## Status -Pre-v1. Not yet functional. +In production. `main` is continuously deployed — every merge to `main` builds +and publishes `:latest` images, so whatever is on `main` is what is running. +Day-to-day work happens on `dev`, which publishes `:dev` images. + +## What's in here + +Five deployable pieces, built by `.forgejo/workflows/build.yml`: + +| Piece | Built from | Image | Role | +| --- | --- | --- | --- | +| **Web / workers** | `Dockerfile` | `fabledcurator` | Quart API + the built Vue SPA in one image. `entrypoint.sh` picks the role: `web`, `worker`, `scheduler`. The `maintenance-long` service is a second `worker` pinned to the long-running maintenance queue. | +| **ML worker** | `Dockerfile.ml` | `fabledcurator-ml` | Same app, plus `requirements-ml.txt` — tagging and embedding models that run in-container. | +| **GPU agent** | `agent/Dockerfile` | `fabledcurator-agent` | Optional desktop-GPU worker (`agent/`). Leases jobs over **HTTP only** — never touches the database or Redis. Run it for a burst, stop it to reclaim the card. See `agent/README.md`. | +| **Firefox extension** | `extension/` | signed XPI | MV3 extension: pushes platform session cookies into FC and adds a creator as a Source in one click. AMO-signed on `main` only, then bundled into the web image and served from Settings → Maintenance. See `extension/README.md`. | +| **Data** | — | `pgvector/pgvector:pg16`, `redis:7-alpine` | Postgres with pgvector for embeddings; Redis as the Celery broker. | ## Quick start @@ -29,22 +43,37 @@ docker compose -f docker-compose.yml up -d # (skips the override so containers pull registry images) ``` +The GPU agent is deployed separately, on the machine with the card — +`agent/docker-compose.yml`, not this stack. + ## Deployment posture FabledCurator is designed to run inside a self-hosted homelab environment over plain HTTP. If you want TLS, terminate it at your reverse proxy. The app does not generate certificates, redirect to HTTPS, or set HSTS. ## CI / Forgejo setup -The repo's workflows expect: +Three workflows: `ci.yml` (lint, extension-version guard, backend unit tests, +frontend build, integration), `extension.yml` (extension lint, vitest, XPI +content verification), and `build.yml` (sign + publish). -- **Runner label `python-ci`** — a Forgejo runner with Python 3.14, ruff, and Node 22 pre-installed. Both `ci.yml` and `build.yml` use this label. The runner image (`runner-base:python-ci`) is built from `CI-Runner/CI-python/` in the operator's workspace; `make push` from that directory builds and pushes a new image when toolchain pins change. -- **Repo secret `RELEASE_TOKEN`** — a Forgejo PAT with the following scopes: +**The toolchain each job runs in is its `container.image`, not its `runs-on` +label.** `runs-on: python-ci` only schedules the job onto a runner; every job +then names the image it actually wants. `ci-requirements.md` is the current, +authoritative list of images and per-job installs — read that rather than a +copy here, so the two can't drift. + +The repo expects one secret: + +- **`RELEASE_TOKEN`** — a Forgejo PAT with: - `write:package` + `read:package` — for `docker push` to `git.fabledsword.com` - - `write:release` — for future release-cutting workflows - - `write:issue` — for future issue-management automation + - `write:release` — for the `ext-` releases that cache the signed XPI + - `write:issue` — for issue-management automation Generate at https://git.fabledsword.com/user/settings/applications. The injected `GITHUB_TOKEN` cannot be used because it lacks `write:package`. +AMO signing additionally needs `MOZILLA_AMO_JWT_KEY` / `MOZILLA_AMO_JWT_SECRET`; it runs on +`main` only and is cached per version, since AMO rejects a re-signed version. + ## License Personal project; use at your own discretion.