docs: rewrite Installation section for v0.1.x deployment#135
Conversation
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 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 44bb36e9de
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # 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 |
There was a problem hiding this comment.
This step tells operators to create deploy/.env, but the compose stack reads ../.env (deploy/docker-compose.yml uses env_file: ../.env and required ${PROCESSGIT_UPDATER_TOKEN:?...} interpolation), and deploy/.env.example itself says to copy to ../.env. Following these instructions leaves Compose looking at a different file than the one the user edited, which can make first-time deployment and later version pin updates fail.
Useful? React with 👍 / 👎.
|
|
||
| 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: |
There was a problem hiding this comment.
The documented opt-out path says to omit PROCESSGIT_UPDATER_TOKEN and start processgit, but processgit itself requires that variable in deploy/docker-compose.yml (PROCESSGIT_UPDATER_TOKEN: ${PROCESSGIT_UPDATER_TOKEN:?...}). In this configuration, Compose errors before startup when the token is unset, so this path is not executable for users trying to disable the sidecar.
Useful? React with 👍 / 👎.
| curl -s -H "Authorization: Bearer $TOKEN" \ | ||
| http://localhost:9000/releases/latest | jq |
There was a problem hiding this comment.
This command queries http://localhost:9000/releases/latest, but processgit-updater does not publish port 9000 in deploy/docker-compose.yml; it is only reachable on the internal Compose network as processgit-updater:9000 (as your next command already assumes via docker compose ... exec processgit). Users running this exact command on the host will get connection failures.
Useful? React with 👍 / 👎.
1 participant
docs: rewrite Installation section for v0.1.x deployment
The README's Installation section dated to pre-v0.1.0 and would literally fail if a new user followed it. This rewrite reflects the actual v0.1.x flow.
What was broken in the old Installation section
http://localhost:3000http://localhost:18080(compose maps 18080:3000)docker compose up -d --build(build from source)docker compose up -d(pull signed images from GHCR)deploy/.env.envfilecosign verify(PR #127)New section layout
.envcosign verifyagainst the workflow's OIDC identity--buildworkflow for devsKey UX wins
1. "One install, four containers" mental model. A new section explicitly states that ProcessGit is one Docker Compose project with four services, three of which are usually invisible (one-shot init + one-shot bootstrap + the long-running updater). Disabuses the "do I need two installers?" confusion that triggered this cleanup pass.
2. Opt-out path is documented, not buried. Operators with change-control processes (PwC, govt sandbox) can skip the updater cleanly without editing compose files. Two methods documented: don't set the token, or stop the service after
up.3. Update flow is documented for both paths. With-sidecar previews the admin UI (Slice 4, coming) and shows the curl-based control surface available today. Without-sidecar documents the standard
sed PROCESSGIT_VERSION + compose pull + upflow.4. Build-from-source preserved for developers. The old
--buildworkflow isn't lost — it's just moved to its own subsection so it doesn't confuse end-users.Quick-start preview
The new opening section reads:
Four commands. One file. Done.
Sequencing with PR #134
This README references
deploy/.envas the single config file. That's only true once PR #134 (single-env cleanup) merges. Best landed after #134, or merged together. If this lands first, the README will document a flow that requires PR #134 to actually work.Diff stat
No other section of the README changed.