ReachableCEO
27948346b4
- Update collab/TSYSDevStack-toolbox-prompt.md with latest guidelines - Update output/PROMPT with improved instructions for AI collaboration - Update output/toolbox-base/PROMPT with enhanced development guidelines - Update output/toolbox-base/README.md with current documentation - Update output/toolbox-base/build.sh with improved build process - Update output/toolbox-base/docker-compose.yml with refined service definitions - Update output/toolbox-base/run.sh with enhanced runtime configuration - Add output/toolbox-base/release.sh for release management processes These changes improve the developer workspace experience and ensure consistent tooling across the TSYSDevStack project.
93 lines
5.1 KiB
Markdown
93 lines
5.1 KiB
Markdown
# 🧰 TSYSDevStack Toolbox Base
|
|
|
|
Daily-driver development container for ToolboxStack work. It provides a reproducible Ubuntu 24.04 environment with curated shell tooling, package managers, and helper scripts.
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
1. **Build the image (local dev tag)**
|
|
```bash
|
|
./build.sh
|
|
```
|
|
> Builds and tags the image as `tsysdevstack-toolboxstack-toolbox-base:dev`. Uses `docker buildx` with a local cache at `.build-cache/` for faster rebuilds.
|
|
2. **Start the container**
|
|
```bash
|
|
./run.sh up
|
|
```
|
|
> Defaults to the `release-current` tag; override with `TOOLBOX_IMAGE_OVERRIDE=...` when testing other tags. Mise runtimes persist to your host in `~/.local/share/mise` and `~/.cache/mise` so language/tool downloads are shared across projects.
|
|
3. **Attach to a shell**
|
|
```bash
|
|
docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh
|
|
# or: bash / fish
|
|
```
|
|
4. **Stop the container**
|
|
```bash
|
|
./run.sh down
|
|
```
|
|
|
|
The compose service mounts the current repo to `/workspace` (read/write) and runs as the mapped host user (`toolbox`).
|
|
|
|
---
|
|
|
|
## 🏷️ Image Tagging & Releases
|
|
|
|
- `./build.sh` (no overrides) ⇒ builds `:dev` for active development.
|
|
- `./release.sh <semver>` ⇒ rebuilds, retags, and pushes `:dev`, `:release-current`, and `v<semver>` (e.g., `./release.sh 0.2.0`). Requires a clean git tree.
|
|
- Add `--dry-run` to rehearse the release without pushing (optionally `--allow-dirty` for experimentation only).
|
|
- Downstream Dockerfiles should inherit from `tsysdevstack-toolboxstack-toolbox-base:release-current` (or pin to a semantic tag for reproducibility).
|
|
|
|
---
|
|
|
|
## 🧩 Tooling Inventory
|
|
|
|
| Category | Tooling | Notes |
|
|
|----------|---------|-------|
|
|
| **Shells & Prompts** | 🐚 `zsh` • 🐟 `fish` • 🧑💻 `bash` • ⭐ `starship` • 💎 `oh-my-zsh` | Starship prompt enabled for all shells; oh-my-zsh configured with `git` + `fzf` plugins. |
|
|
| **Runtime & CLI Managers** | 🪄 `mise` • 💧 `aqua` | `mise` handles language/tool runtimes (activation wired into zsh/bash/fish); `aqua` manages standalone CLIs with config at `~/.config/aquaproj-aqua/aqua.yaml`. |
|
|
| **Core CLI Utilities** | 📦 `curl` • 📥 `wget` • 🔐 `ca-certificates` • 🧭 `git` • 🔧 `build-essential` + headers (`pkg-config`, `libssl-dev`, `zlib1g-dev`, `libffi-dev`, `libsqlite3-dev`, `libreadline-dev`, `make`) • 🔍 `ripgrep` • 🧭 `fzf` • 📁 `fd` • 📖 `bat` • 🔗 `openssh-client` • 🧵 `tmux` • 🖥️ `screen` • 📈 `htop` • 📉 `btop` • ♻️ `entr` • 📊 `jq` • 🌐 `httpie` • ☕ `tea` • 🧮 `bc` | Provides ergonomic defaults plus toolchain deps for compiling runtimes (no global language installs). |
|
|
| **Aqua-Managed CLIs** | 🐙 `gh` • 🌀 `lazygit` • 🪄 `direnv` • 🎨 `git-delta` • 🧭 `zoxide` • 🧰 `just` • 🧾 `yq` • ⚡ `xh` • 🌍 `curlie` • 🏠 `chezmoi` • 🛠️ `shfmt` • ✅ `shellcheck` • 🐳 `hadolint` • 🐍 `uv` • 🔁 `watchexec` | Extend via `~/.config/aquaproj-aqua/aqua.yaml` and run `aqua install`. Direnv logging is muted and hooks for direnv/zoxide are pre-configured for zsh, bash, and fish. |
|
|
| **Container Workflow** | 🐳 Docker socket mount (`/var/run/docker.sock`) | Enables Docker CLIs inside the container; host Docker daemon required. |
|
|
| **Runtime Environment** | 👤 Non-root user `toolbox` (UID/GID mapped) • 🗂️ `/workspace` mount | Maintains host permissions and isolates artifacts under `artifacts/ToolboxStack/toolbox-base`. |
|
|
|
|
---
|
|
|
|
## 🛠️ Extending the Sandbox
|
|
|
|
- **Add a runtime**: `mise use python@3.12` (per project). Run inside `/workspace` to persist `.mise.toml`.
|
|
- **Add a CLI tool**: update `~/.config/aquaproj-aqua/aqua.yaml`, then run `aqua install`.
|
|
- **Adjust base image**: modify `Dockerfile`, run `./build.sh`, and keep this README & `PROMPT` in sync.
|
|
|
|
> 🔁 **Documentation policy:** Whenever you add/remove tooling or change the developer experience, update both this README and the `PROMPT` file so the next collaborator has an accurate snapshot.
|
|
|
|
---
|
|
|
|
## 📂 Project Layout
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `Dockerfile` | Defines the toolbox-base image. |
|
|
| `docker-compose.yml` | Compose service providing the container runtime. |
|
|
| `build.sh` | Wrapper around `docker build` with host UID/GID mapping. |
|
|
| `run.sh` | Helper to bring the compose service up/down (exports UID/GID env vars). |
|
|
| `.devcontainer/devcontainer.json` | VS Code remote container definition. |
|
|
| `aqua.yaml` | Default aqua configuration (gh, tea, lazygit). |
|
|
| `PROMPT` | LLM onboarding prompt for future contributors (must remain current). |
|
|
|
|
---
|
|
|
|
## ✅ Verification Checklist
|
|
|
|
After any image changes:
|
|
1. Run `./build.sh` and ensure it succeeds.
|
|
2. Optionally `./run.sh up` and sanity-check key tooling (e.g., `mise --version`, `gh --version`).
|
|
3. Update this README and the `PROMPT` with any new or removed tooling.
|
|
|
|
---
|
|
|
|
## 🤝 Collaboration Notes
|
|
|
|
- Container always runs as the mapped non-root user; avoid adding steps that require root login.
|
|
- Prefer `mise`/`aqua` for new tooling to keep installations reproducible.
|
|
- Keep documentation synchronized (README + PROMPT) so future contributors can resume quickly.
|