v0.1.4: partner-ready install docs + real-updates default#140
Conversation
Tightens up the install story for hand-off to external operators after v0.1.3 validated the full install path end-to-end. Three substantive changes plus one cosmetic. 1. README Installation section rewritten (substantive) The previous Installation section was written before the install path actually worked end-to-end. Now that PRs #138-#139 fixed the install-wizard skip and the SSH-dir perms, and a fresh `docker compose up -d` actually produces a healthy ProcessGit instance, the README reflects the validated reality: - Hard prerequisites in a table (RAM, disk, ports, outbound network) - Three-command quick start matching what we just verified on docker-vps: curl the compose file, write a 2-line .env, up -d. No git clone, no source build. - First-time setup section explaining the first-user-as-admin Gitea convention so operators know how to log in - Verify signed images via cosign (was already documented; left as-is) - Updating section now points at the admin UI at /-/admin/updates (Slice 4, PR #136). Previously said "in a future release"; the future is now. - Configuration table with the env vars init-config reads, including PROCESSGIT_ROOT_URL which is critical because the admin UI shows a warning banner if the request hostname doesn't match what was set on first boot. - Opt-out instructions for the self-update sidecar - Troubleshooting table covering every failure mode we hit during the v0.1.0→v0.1.3 install validation, so future operators can self-serve. - Installing Docker on Ubuntu/WSL kept at the bottom - Pointer to DEVELOPING.md for from-source builds A prominent blockquote at the top of the section says this is the only supported install method, because the admin UI's self-update flow expects the exact compose layout shipped. 2. DEVELOPING.md added for contributors building from source Pulls the "from source / iteration" content out of the README into its own document so the README reads as an operator-facing product page. Covers: repo structure, local build, test commands, build-from-source compose flag, release process. 3. Real updates by default (substantive) PROCESSGIT_UPDATER_STUB in docker-compose.yml flipped from default `true` to default `false`. Slice 3B (#131) has been merged for a while, so real docker swap operations work. Defaulting to stub mode meant admin-UI "Install" clicks went through the state machine but didn't actually update anything, which is the opposite of what a fresh operator expects. Operators who specifically want stub mode (for testing the UI flow without committing real updates) can still opt in by setting PROCESSGIT_UPDATER_STUB=true in deploy/.env. 4. Workflow release notes cosmetic (small) Drop the hardcoded "linux/arm64" line and rephrase the "Multi-arch Docker image" string in .github/workflows/release.yml's Summary step. Current images are amd64-only; the lines were placeholders for when an ARM64 runner becomes available. Files: MOD README.md ~200 lines reworked in the Installation section NEW DEVELOPING.md contributor docs MOD deploy/docker-compose.yml stub default flipped MOD .github/workflows/release.yml cosmetic strings 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: ad38f41635
ℹ️ 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".
| | Symptom | Likely cause | Fix | | ||
| |---|---|---| | ||
| | `processgit` "unhealthy" forever | Slow host; first-boot Gitea init exceeds healthcheck `start_period` | Wait 90 seconds, recheck with `docker compose ps`. If still unhealthy, see logs below. | | ||
| | `permission denied` for `/data/git/.ssh/authorized_keys.tmp` in logs | Running an image older than v0.1.3 with a current compose file | `docker compose pull && docker compose down -v && docker compose up -d` | |
There was a problem hiding this comment.
down -v from recovery instructions
The troubleshooting fix for the authorized_keys.tmp permission error tells operators to run docker compose down -v, which deletes named volumes and therefore wipes repository data for an existing deployment. In this compose stack, persistent state is stored in the named processgit-data volume (deploy/docker-compose.yml), so following this instruction on a live instance can cause irreversible data loss while attempting a routine repair.
Useful? React with 👍 / 👎.
| | `PROCESSGIT_SSH_PORT` | `12222` | External SSH port. Display only — the container always listens on 22 internally. | | ||
| | `PROCESSGIT_VERSION` | `latest` | Pin a specific image tag. Leave unset to auto-track `latest`. | | ||
|
|
||
| These are read by the `processgit-init-config` step on **first boot only**. After that, edit `/data/gitea/conf/app.ini` inside the volume directly to change them — see the [Gitea config cheatsheet](https://docs.gitea.com/administration/config-cheat-sheet) for the full surface area. |
There was a problem hiding this comment.
.env values are first-boot only
This sentence incorrectly implies all listed deploy/.env variables are only consumed by processgit-init-config on first boot and should later be changed via app.ini. That is not true for PROCESSGIT_VERSION and PROCESSGIT_UPDATER_TOKEN, which are read by Compose/service runtime on each docker compose up (see image: ...${PROCESSGIT_VERSION...} and updater environment in deploy/docker-compose.yml). Following the current guidance can lead operators to edit the wrong place and fail to pin versions or rotate updater auth correctly.
Useful? React with 👍 / 👎.
1 participant
v0.1.4: partner-ready install docs + real-updates default
Tightens up the install story for hand-off to external operators. After v0.1.3 validated the full install path end-to-end on a fresh VPS, the docs that describe how to do that install are now actually accurate. Three substantive changes plus one cosmetic.
1. README Installation section — rewritten
The previous version was written before we had a working install. Now reflects validated reality:
curlcompose file → 2-line.env→up -d. Nogit clone, no source build./-/admin/updates(Slice 4 / Slice 4: admin UI for self-updates at /-/admin/updates #136). Previously said "in a future release" — the future is now.init-configreads, includingPROCESSGIT_ROOT_URLwhich is critical (otherwise admin UI shows the warning banner we saw in the v0.1.3 screenshot).Prominent blockquote at the top:
2. DEVELOPING.md — new
Pulls "from source / iteration" content out of the README so the README reads as a clean operator-facing product page. Covers: repo structure, local build, test commands, build-from-source compose flag, release process.
3. Real updates by default
PROCESSGIT_UPDATER_STUBindocker-compose.ymlflipped from defaulttrue→ defaultfalse. Slice 3B (#131) shipped real docker swap operations weeks ago, but the compose still defaulted to stub mode. Admin-UI Install clicks would walk the state machine cosmetically without actually swapping anything — confusing for operators expecting the update to take effect.Operators who specifically want stub mode for testing the UI flow without committing real updates can still opt in via
PROCESSGIT_UPDATER_STUB=trueindeploy/.env.4. Workflow release notes cosmetic
Drop the hardcoded
linux/arm64line and rephrase "Multi-arch Docker image" in the release notes generator. Current images are amd64-only; those lines were aspirational placeholders for when an ARM64 runner becomes available.Diff inventory
README.mdDEVELOPING.mddeploy/docker-compose.ymlfalse.github/workflows/release.ymlValidation
Sequencing
Merge → tag
v0.1.4against new main HEAD → workflow publishes signed images with the docs-corrected release notes. Then you can test the admin UI's Install button on your current v0.1.3 instance: it'll surface v0.1.4 as available and clicking Install will trigger a real container swap (not stub-mode, since the default flipped).After this lands and the update test confirms green, the GitHub repo URL is ready to share with the corporate sysadmin.
Prerequisite for partner handoff (action on you)
The repo needs to be public for the unauthenticated
curlin the Quick Start to work. Right now it's private, andraw.githubusercontent.comreturns 404 to anonymous requests. The README's Quick Start commands won't work for the partner sysadmin you're sending the URL to unless:Contents:Readpermission. The README would then need rewording to mandate auth. Less clean.Recommend Option A given everything else (images on GHCR, release manifests) is already public.