diff --git a/.gitea/workflows/docker-publish.yml b/.gitea/workflows/docker-publish.yml index c4243b1..f37dc1f 100644 --- a/.gitea/workflows/docker-publish.yml +++ b/.gitea/workflows/docker-publish.yml @@ -409,7 +409,20 @@ jobs: steps: - uses: actions/checkout@v4 - name: Update Docker Hub description + env: + PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }} run: | + # Substitute {{PI_VERSION}} placeholders in DOCKER_HUB.md so the + # Hub page always shows which pi version is in :latest. The + # placeholder lives in DOCKER_HUB.md (committed); CI fills it + # at publish time using the same resolved version that was + # baked into the variant image. No drift between page and image. + cp DOCKER_HUB.md /tmp/hub-full.md + sed -i "s/{{PI_VERSION}}/${PI_VERSION}/g" /tmp/hub-full.md + if grep -q '{{PI_VERSION}}' /tmp/hub-full.md; then + echo "::error::DOCKER_HUB.md still contains unsubstituted {{PI_VERSION}} markers" + exit 1 + fi TOKEN=$(curl -s -X POST https://hub.docker.com/v2/auth/token \ -H "Content-Type: application/json" \ -d '{"identifier":"${{ vars.DOCKERHUB_USERNAME }}","secret":"${{ secrets.DOCKERHUB_TOKEN }}"}' \ @@ -419,7 +432,7 @@ jobs: exit 1 fi HTTP_CODE=$(jq -n \ - --rawfile full DOCKER_HUB.md \ + --rawfile full /tmp/hub-full.md \ --arg short "Linux container with the pi coding-agent, MemPalace, and curated dev tooling." \ '{"full_description": $full, "description": $short}' | \ curl -s -o /tmp/hub-response.txt -w "%{http_code}" -X PATCH \ @@ -433,4 +446,4 @@ jobs: echo "::error::Docker Hub description update failed with HTTP $HTTP_CODE" exit 1 fi - echo "Description updated." + echo "Description updated (pi version: ${PI_VERSION})." diff --git a/DOCKER_HUB.md b/DOCKER_HUB.md index d26383a..863a594 100644 --- a/DOCKER_HUB.md +++ b/DOCKER_HUB.md @@ -1,15 +1,17 @@ # pi-devbox -A Docker container with [pi coding-agent](https://github.com/earendil-works/pi) pre-installed, built on top of [opencode-devbox](https://hub.docker.com/r/joakimp/opencode-devbox)'s base image. Pi gets a fully-loaded development environment in one `docker run`. +A self-contained Docker container for the [pi coding-agent](https://github.com/earendil-works/pi) — pi + companion repos + MemPalace + a curated set of dev tooling, ready to run. + +> **Current `:latest` ships pi `{{PI_VERSION}}`** (resolved at build time; see [Versioning](#versioning)). ## Image variants -| Tag | Size (compressed) | What you get | -|---|---|---| -| `joakimp/pi-devbox:latest` | ~700 MB | Pi + companion repos, on top of the opencode-devbox base | -| `joakimp/pi-devbox:vX.Y.Z` | same | Pinned pi version (tracks the [pi npm package version](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)) | - -Multi-arch: `linux/amd64`, `linux/arm64`. +| Tag | Architectures | Size (compressed) | What you get | +|---|---|---|---| +| `joakimp/pi-devbox:latest` | amd64, arm64 | ~1.1 GB | Self-contained: base + pi `{{PI_VERSION}}` + companions | +| `joakimp/pi-devbox:vX.Y.Z` | amd64, arm64 | same | Pinned semver release | +| `joakimp/pi-devbox:base-latest` | amd64, arm64 | ~1.0 GB | Base layer alias (internal building block; pull `:latest` instead) | +| `joakimp/pi-devbox:base-` | amd64, arm64 | ~1.0 GB | Content-addressed base; immutable. Stable parent for variant rebuilds. | ## Quick start @@ -38,42 +40,82 @@ Full setup guide — authentication for each provider (Anthropic, OpenAI, Gemini ## What's inside -pi-devbox is a re-brand of the **pi-only build** — it builds -`FROM joakimp/pi-devbox:base-pi-only` and adds no layers of its own. That -building-block tag is produced by opencode-devbox's CI (from -`Dockerfile.variant` with `INSTALL_OPENCODE=false`) but published here, in the -pi-devbox repo, so an opencode-devbox tag never ships without opencode. -The pi-only build is lean -and pi-focused (no opencode — use `opencode-devbox:latest-with-pi` if you want -both). -Everything below is inherited from that single source of truth. +### pi and companions -Base tooling: - -- **Debian trixie** (latest stable) -- **Node.js** (LTS), **uv** (Python tooling), **rustup** (Rust on-demand) -- **AWS CLI v2** + AWS Bedrock-ready config -- **MemPalace** + MCP server — persistent agent memory across sessions, queryable via `mempalace_*` tools inside pi -- **Gitea MCP** server -- **Dev tools**: neovim (LazyVim defaults), tmux, bat, eza, fzf, zoxide, ripgrep, git-lfs, make -- **Shell**: bash with history tuning, prefix-search bindings, fzf/zoxide integration -- **Host-OS-agnostic LAN access** — on VM-backed hosts (macOS OrbStack / Docker Desktop) the host is set up as an SSH jump to reach LAN peers (`dssh` alias; `DEVBOX_LAN_ACCESS`/`HOST_SSH_USER`). No-op on native Linux. - -pi and companions: - -- **pi** ([`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)) — baked at `/usr/bin/pi`, version set by the pi-only base build +- **pi `{{PI_VERSION}}`** ([`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)) — installed at `/usr/bin/pi` - **[pi-toolkit](https://gitea.jordbo.se/joakimp/pi-toolkit)** — keybindings (mosh/tmux-friendly Shift+Enter, Ctrl+J, Alt+J newline bindings), AWS env loader, settings template - **[pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions)** — 7 user-facing extensions: `ext-toggle`, `mcp-loader`, `todo`, `ssh-controlmaster`, `notify`, `git-checkpoint`, `confirm-destructive` - **`fork`** ([pi-fork](https://github.com/elpapi42/pi-fork)) and **`recall`** ([pi-observational-memory](https://github.com/elpapi42/pi-observational-memory)) tools -- **mempalace bridge** — MCP extension auto-symlinked so pi can read/write the same palace as opencode-devbox +- **mempalace bridge** — MCP extension auto-symlinked so pi reads/writes the host-mounted palace The entrypoint deploys/registers all of these on first container start. Re-running is idempotent and preserves user edits. +### MemPalace (persistent agent memory) + +- **MemPalace** + MCP server — semantic search over conversation history, knowledge graph, diary; queryable via 29 `mempalace_*` tools inside pi +- ChromaDB ONNX embedding model pre-warmed at build time (`all-MiniLM-L6-v2`) +- Bind-mount your host's `~/.mempalace` and the host-pi and container-pi share one brain + +### Document and image tooling + +- **pandoc** — universal Markdown↔HTML/Org/RST/etc. conversion. Useful well beyond pi: agent-driven doc exports, format conversion, etc. +- **graphviz** (`dot`) — diagram rendering pipelines +- **imagemagick** (`magick`) — image conversion / resizing + +### Modern CLI tooling + +- **Editor**: neovim (LazyVim defaults), tmux (configured for 0-indexed sessions) +- **Search/nav**: ripgrep, fd, fzf, zoxide +- **Display**: bat, eza, htop, tree +- **Data**: jq, yq +- **Help**: tldr (tealdeer — Rust port; run `tldr --update` once to populate cache) +- **Git**: git-lfs, git-crypt, gitleaks (for pre-commit secret scanning) +- **Build**: gcc, g++, make, patch +- **Misc**: gosu, age, rsync, less + +### Language toolchains + +- **Python**: system Python 3 + **uv** (preferred) for fast Python package management. Run any Python REPL/notebook stack on demand without bloating the image: + ```bash + uv run --with ipython ipython + uv run --with jupyterlab jupyter lab --no-browser --port 8888 + uv run --with marimo marimo edit + ``` +- **Node.js** v22 + npm (used by pi itself) +- **Rust** — `rustup-init` is on PATH; install toolchains on demand +- **Go** — opt-in via `--build-arg INSTALL_GO=true` if rebuilding from source + +### Cloud + secrets + +- **AWS CLI v2** — for SSO + Bedrock auth (pi's preferred LLM provider for the maintainer's setup) +- **Gitea MCP** server — for Gitea API access from inside pi +- **age**, **git-crypt** — encryption tooling + +### SSH and networking + +- OpenSSH client with **ControlMaster auto** preconfigured on a writable socket path (`/tmp/sshcm/`). Mitigates ssh banner-exchange failures behind CGNAT-restricted residential ISPs (~4-flow caps). +- A **LAN-access helper** that auto-configures ssh jump-via-host on VM-backed hosts (OrbStack / Docker Desktop on macOS) so the container can reach the host's directly-attached LAN peers (`dssh ` alias; `DEVBOX_LAN_ACCESS` / `HOST_SSH_USER`). + ## Versioning -Tags follow the pi npm version: `v0.74.0`, `v0.75.0`, etc. `latest` always points at the most recent release. The pi binary is inherited from `joakimp/pi-devbox:base-pi-only`, so each release follows an opencode-devbox release that bakes the target pi version. (`base-pi-only` is an internal building-block tag — pull `latest` or a `vX.Y.Z` tag instead.) +From v1.0.0 onward, pi-devbox uses **semver**: -For container-level rebuilds on the same pi version (security updates, base bumps, fixes) the tag gets a letter suffix: `v0.74.0b`, `v0.74.0c`, … +- **Major** — architectural changes. v1.0.0 is the first decoupled release, where pi-devbox got its own self-contained build chain (previously it was a thin re-brand of opencode-devbox's `pi-only` variant). +- **Minor** — new image variants, significant base additions. +- **Patch** — pi version bumps, smaller fixes. + +The pi binary version inside any given release is shown in this description (currently **`{{PI_VERSION}}`** for `:latest`) and asserted by smoke tests to match what's documented — version drift is caught at CI time, not on user pull. + +> **Pre-v1.0.0 history.** Tags v0.74.0…v0.79.0 followed the pi npm version directly (`v{pi_version}[letter]`). Those images remain on Hub but are deprecated in favor of `:latest` / `:v1.X.Y`. The legacy `:base-pi-only*` tags were CI artifacts of the old opencode-devbox-based build pipeline; they will be removed in a future opencode-devbox v2.0.0. + +### Build pipeline + +pi-devbox is built in two phases: + +1. **Base** (`Dockerfile.base`) → `base-` tag, content-addressed over `Dockerfile.base` + `rootfs/` + `entrypoint*.sh`. Rebuilt only when those change. +2. **Variant** (`Dockerfile.variant`) → `:latest` and `:vX.Y.Z`. FROMs the base, adds the pi install + companions. + +`base-latest` is an alias of the most recent base. ## Persistent state @@ -86,6 +128,7 @@ User edits and pi-installed packages survive container recreation when you mount | `devbox-zoxide` | `/home/developer/.local/share/zoxide` | zoxide directory jump database | | `devbox-nvim-data` | `/home/developer/.local/share/nvim` | neovim plugin & Mason package state | | `devbox-uv` | `/home/developer/.local/share/uv` | uv Python installs and tool cache | +| `devbox-ssh-local` | `/home/developer/.ssh-local` | LAN-jump key (one-time host authorization survives recreate) | Optional volumes for MemPalace (commented out by default — uncomment in `docker-compose.yml` to persist conversation memory across restarts): @@ -101,10 +144,10 @@ Optional volumes for MemPalace (commented out by default — uncomment in `docke ## Source - **This image**: https://gitea.jordbo.se/joakimp/pi-devbox -- **Base image**: https://gitea.jordbo.se/joakimp/opencode-devbox (Hub: `joakimp/opencode-devbox`) - **pi**: https://github.com/earendil-works/pi - **pi-toolkit**: https://gitea.jordbo.se/joakimp/pi-toolkit - **pi-extensions**: https://gitea.jordbo.se/joakimp/pi-extensions +- **MemPalace**: https://github.com/joakimp/mempalace ## License