🧰 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

Build the image
```
./build.sh
```
Uses docker buildx with a local cache at .build-cache/ for faster rebuilds.
Start the container
```
./run.sh up
```
Mise runtimes persist to your host in ~/.local/share/mise and ~/.cache/mise so language/tool downloads are shared across projects.

Attach to a shell

docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh
# or: bash / fish

Stop the container
```
./run.sh down
```

The compose service mounts the current repo to /workspace (read/write) and runs as the mapped host user (toolbox).

🧩 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:

Run ./build.sh and ensure it succeeds.
Optionally ./run.sh up and sanity-check key tooling (e.g., mise --version, gh --version).
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.

4.4 KiB Raw Blame History