From 44bb36e9dec336fb26b8097ee79c3a2709209669 Mon Sep 17 00:00:00 2001 From: Rihards Gailums Date: Sat, 23 May 2026 18:57:29 +0000 Subject: [PATCH] docs: rewrite Installation section for v0.1.x deployment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Installation section in the README dated to pre-v0.1.0 and would literally fail if a new user followed it: - Said port 3000 (compose maps host port 18080 → container 3000) - Used `docker compose up --build` (build-from-source flow) instead of pulling signed images from ghcr.io - Made no mention of the processgit-updater sidecar (added in PR #128) - Made no mention of deploy/.env / .env.example (added in PR #130) - Made no mention of cosign verification (introduced in #127) - Would error on `compose up` with PROCESSGIT_UPDATER_TOKEN missing This rewrite reflects the actual v0.1.x flow (assuming PR #134 "collapse to single .env" lands; the new instructions reference deploy/.env exclusively). New section layout: ### Prerequisites (unchanged) ### Quick Start (rewritten — 4 commands, single .env) ### Verify the signed release (new — cosign verify against the OIDC identity) ### The four services (new — table explaining what runs and why) ### Opt out of self-update (new — addresses operator UX concern) ### Verify Template Bootstrap (port number updated) ### Updating (new — both with-sidecar and manual flows) ### Redeploy / rebuild (commands updated) ### Build from source (new — preserves --build for devs) ### Install Docker (unchanged; still accurate) The "Opt out" subsection deliberately spells out two ways to skip the updater (don't set the token, OR stop the service after the fact) because that operator UX concern was explicit feedback: change-controlled deployments (PwC, gov sandbox, LADUS) need to be able to skip self-update cleanly. The "Updating" subsection previews the admin UI path (Slice 4, coming) and documents the manual sed-PROCESSGIT_VERSION-and-compose-up flow that works today without the sidecar. The "Build from source" subsection preserves the --build flow for people working on the Gitea-layer code, so the old workflow isn't lost. Co-authored-by: Claude --- README.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 101 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 31c5032..453ccca 100644 --- a/README.md +++ b/README.md @@ -651,21 +651,74 @@ DEFAULT_PROVIDER = anthropic ### Prerequisites - Linux (Ubuntu 20.04+ recommended) or WSL2 -- Docker Engine + Docker Compose (plugin) -- Git +- Docker Engine + Docker Compose plugin (v2) +- Git (for cloning the deploy files; the app images themselves are pulled from GHCR) ### Quick Start +A ProcessGit deployment is **one Docker Compose project with four services**: the main app, a one-shot permissions initializer, a one-shot template bootstrap, and an optional self-update sidecar. `docker compose up` brings them all up in dependency order. No second installer, no separate setup script. + ```bash -# Clone the repository -git clone https://github.com/Algomation-AI/ProcessGit.git +# 1. Get the deploy files (compose + bootstrap templates). +git clone --branch v0.1.0 https://github.com/Algomation-AI/ProcessGit.git cd ProcessGit -# Build and start -docker compose -f deploy/docker-compose.yml up -d --build +# 2. Create the env file from the template. +cp deploy/.env.example deploy/.env + +# 3. (Recommended) Generate a token so the self-update sidecar can run. +# Skip this step if you don't want in-product self-updates. +echo "PROCESSGIT_UPDATER_TOKEN=$(openssl rand -hex 32)" >> deploy/.env + +# 4. Start everything. Pulls signed images from ghcr.io. +docker compose -f deploy/docker-compose.yml up -d ``` -The application will be available at `http://localhost:3000`. +The application is now available at **`http://localhost:18080`** (host port 18080 maps to container port 3000). The first start takes ~30–60 seconds while the bootstrap container seeds template repos. + +All operator configuration lives in **a single file**: `deploy/.env`. See `deploy/.env.example` for the available keys (image version pin, app config like `DOMAIN`/`ROOT_URL`, updater settings). + +### Verify the signed release + +Every ProcessGit Docker image and release manifest is keyless-signed via [Sigstore](https://www.sigstore.dev/) by the GitHub Actions workflow that built it. To verify before deploying: + +```bash +cosign verify ghcr.io/algomation-ai/processgit:0.1.0 \ + --certificate-identity-regexp '^https://github.com/Algomation-AI/ProcessGit/\.github/workflows/release\.yml@.*' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com +``` + +The same verification works against `ghcr.io/algomation-ai/processgit-updater:0.1.0` and against the `release.json` blob attached to each GitHub Release. + +### The four services + +| Service | What it does | Lifecycle | +| --- | --- | --- | +| `processgit-init-perms` | Sets up data-dir permissions on the persistent volume | Runs once, exits | +| `processgit` | The main app on port 18080 (host) → 3000 (container) | Long-running | +| `processgit-bootstrap` | Seeds template repos via the API after the main app is healthy | Runs once, exits | +| `processgit-updater` | Self-update sidecar with internal HTTP API; **optional** | Long-running | + +The updater sidecar is intentionally a separate container, not a thread inside the main app, for two reasons: a container fundamentally can't replace itself in place (it would terminate the very process running the swap), and the updater needs `/var/run/docker.sock` access — which we want to keep well away from the public-facing Gitea web server. + +### Opt out of the self-update sidecar + +If you have a change-control process, prefer manual updates, or just want to keep the deployment minimal, skip the sidecar. Two ways: + +1. **Don't set `PROCESSGIT_UPDATER_TOKEN` in `.env`** and start only the services you want: + + ```bash + docker compose -f deploy/docker-compose.yml up -d \ + processgit-init-perms processgit processgit-bootstrap + ``` + +2. **Stop it after the fact:** + + ```bash + docker compose -f deploy/docker-compose.yml stop processgit-updater + ``` + +The main app is fully functional without the updater. You'll just update versions manually (see [Updating](#updating) below). ### Verify Template Bootstrap @@ -676,20 +729,46 @@ After starting, confirm the template repositories were created: docker compose -f deploy/docker-compose.yml logs -n 200 processgit-bootstrap # Verify templates via API -curl -s "http://localhost:3000/api/v1/repo/search?q=&template=true" | head +curl -s "http://localhost:18080/api/v1/repo/search?q=&template=true" | head ``` The template dropdown in the New Repository UI should list starter templates for BPMN, CMMN, DMN, and UAPF packages. -### Redeploy +### Updating + +**With the self-update sidecar enabled (recommended):** in a future release, the admin UI at `/-/admin/updates` will surface available updates and let an administrator install them with one click. Until that page ships, you can talk to the sidecar directly: + +```bash +# What's the latest stable release? +curl -s -H "Authorization: Bearer $TOKEN" \ + http://localhost:9000/releases/latest | jq + +# Trigger an update (the sidecar's internal port; only reachable inside the compose network) +docker compose -f deploy/docker-compose.yml exec processgit \ + curl -s -X POST -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"target_tag":"v0.1.1"}' \ + http://processgit-updater:9000/update +``` + +**Without the sidecar:** standard Docker Compose flow. Pin the new version in `deploy/.env` and bring services up again: ```bash -cd /home/ProcessGit +sed -i 's/^PROCESSGIT_VERSION=.*/PROCESSGIT_VERSION=0.1.1/' deploy/.env +docker compose -f deploy/docker-compose.yml pull +docker compose -f deploy/docker-compose.yml up -d +``` + +### Redeploy / rebuild + +```bash +cd /path/to/ProcessGit docker compose -f deploy/docker-compose.yml down -docker compose -f deploy/docker-compose.yml up -d --build +docker compose -f deploy/docker-compose.yml pull +docker compose -f deploy/docker-compose.yml up -d ``` -To force a bootstrap re-run: +To force a bootstrap re-run (re-seed the template repos): ```bash docker compose -f deploy/docker-compose.yml exec processgit sh -lc \ @@ -697,6 +776,16 @@ docker compose -f deploy/docker-compose.yml exec processgit sh -lc \ docker compose -f deploy/docker-compose.yml restart processgit-bootstrap ``` +### Build from source (developers only) + +The compose file also supports building the main app image locally from the working tree, useful when iterating on Gitea-layer changes: + +```bash +docker compose -f deploy/docker-compose.yml up -d --build +``` + +This builds `deploy/Dockerfile.processgit` against the current source instead of pulling from `ghcr.io`. + ### Install Docker (Ubuntu / WSL) ```bash