DOCKER_HUB.md: expand from stub to full Hub description

Replace the 1-line placeholder with a proper Hub README: image variants table, quick start (docker run + docker compose), inherited-from-base + added-by-pi-devbox feature lists, versioning scheme, persistent volumes table, user-installed pi packages note, source links. Already PATCH'd live on Docker Hub manually — this commit keeps the in-repo file in sync so the next tag-triggered update-description job won't roll it back to the stub.
2026-05-15 08:47:23 +02:00
parent 8ab0f9c760
commit 5d472bd41f
1 changed files with 94 additions and 1 deletions
@@ -1 +1,94 @@
-pi coding-agent container — built on opencode-devbox base. Includes pi, pi-toolkit, pi-extensions, mempalace, AWS CLI, neovim, and full dev toolchain. See https://gitea.jordbo.se/joakimp/pi-devbox for full docs.
+# 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`.
+
+## 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`.
+
+## Quick start
+
+```bash
+docker run -it --rm \
+  -v "$PWD":/workspace \
+  -v "$HOME/.ssh":/home/developer/.ssh:ro \
+  joakimp/pi-devbox:latest pi
+```
+
+For persistent state (settings, bash history, neovim plugins, mempalace data) and a full dev workflow, use docker-compose:
+
+```bash
+git clone https://gitea.jordbo.se/joakimp/pi-devbox
+cd pi-devbox
+cp .env.example .env  # edit WORKSPACE_PATH, GIT_USER_NAME, GIT_USER_EMAIL, etc
+docker compose run --rm devbox
+# inside the container:
+pi
+```
+
+## What's inside
+
+Inherited from [opencode-devbox base](https://hub.docker.com/r/joakimp/opencode-devbox):
+
+- **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
+
+Added by pi-devbox:
+
+- **pi** ([`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)) — baked at `/usr/bin/pi`, version pinned at build time via the `PI_VERSION` build-arg
+- **[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` (manage extensions interactively), `mcp-loader` (load MCP servers via settings.json), `todo`, `ssh-controlmaster`, `notify`, `git-checkpoint`, `confirm-destructive`
+- **mempalace bridge** — MCP extension auto-symlinked from `/opt/mempalace-toolkit` so pi can read/write the same palace as opencode
+
+The entrypoint deploys all of these on first container start. Re-running is idempotent and preserves user edits.
+
+## Versioning
+
+Tags follow the pi npm version: `v0.74.0`, `v0.75.0`, etc. `latest` always points at the most recent release. When pi cuts a new upstream version, this image is rebuilt and re-tagged to match.
+
+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`, …
+
+## Persistent state
+
+User edits and pi-installed packages survive container recreation when you mount these named volumes. Use the included `docker-compose.yml` and they're set up automatically.
+
+| Volume | Mount point | What it holds |
+|---|---|---|
+| `devbox-pi-config` | `/home/developer/.pi/` | pi settings, extension toggles, sessions, user-installed pi packages (`npm install -g`, `pi install npm:…`) |
+| `devbox-shell-history` | `/home/developer/.cache/bash` | bash history |
+| `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 |
+
+Optional volumes for MemPalace (commented out by default — uncomment in `docker-compose.yml` to persist conversation memory across restarts):
+
+| Volume | Mount point | What it holds |
+|---|---|---|
+| `devbox-palace` | `/home/developer/.mempalace` | palace data (drawers, knowledge graph, embeddings) |
+| `devbox-chroma-cache` | `/home/developer/.cache/chroma` | ChromaDB embedding model cache (~80 MB, can be rebuilt) |
+
+## User-installed pi packages
+
+`NPM_CONFIG_PREFIX` is set inside the container to `/home/developer/.pi/npm-global`. Anything you `pi install npm:<pkg>` or `npm install -g` lands on the `devbox-pi-config` named volume — survives container recreation **and** image rebuilds. A user-installed `pi` wins over the baked one via `PATH` order, so you can pin a different pi version without rebuilding the image.
+
+## 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
+
+## License
+
+MIT (the image; pi and the bundled tools each carry their own licenses).