ReachableCEO
3ec443eef8
This commit significantly enhances all documentation files in the ToolboxStack to follow the new beautiful documentation standards: - Updated README.md with comprehensive table of contents, beautiful formatting and icon usage - Enhanced QWEN.md to include instructions on using toolbox-qadocker:release-current for audits - Added section about beautiful documentation requirements (icons, headers, tables, graphics) - Updated toolbox-qadocker README with beautiful formatting, tables, and icon usage - Enhanced toolbox-base README with detailed tables and beautiful formatting - Improved WORKLOG.md with consistent formatting using icons and tables - Added change logs to all documentation files - Followed beautiful documentation principles with consistent icon usage, tables, headers, etc. All documentation now follows the beautiful documentation standard with: - ✨ Use icons (emoji or font-awesome) for better visual appeal - 📊 Use tables to organize information clearly - 🖼️ Include graphics when helpful (ASCII art, diagrams, or links to visual assets) - 🏷️ Use headers to structure content logically - 📝 Include comprehensive change logs with version history - 📋 Include checklists for setup processes - 📊 Add comparison tables when relevant - 📌 Cross-reference related documents clearly
178 lines
7.8 KiB
Markdown
178 lines
7.8 KiB
Markdown
# 🧰 TSYSDevStack Toolbox Base
|
|
|
|
> **Daily-driver development container with curated tooling**
|
|
|
|
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
|
|
|
|
| 📋 Step | 🛠️ Command | 📝 Description |
|
|
|---------|------------|----------------|
|
|
| 1. 🏗️ **Build the image** | `./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** | `./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** | `docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh` | or: `bash` / `fish` |
|
|
| 4. ⏹️ **Stop the container** | `./run.sh down` | Stops the running container |
|
|
|
|
> **💡 Note:** The compose service mounts the current repo to `/workspace` (read/write) and runs as the mapped host user (`toolbox`).
|
|
|
|
---
|
|
|
|
## 🏷️ Image Tagging & Releases
|
|
|
|
| 🛠️ Operation | 📋 Command | 📝 Details |
|
|
|--------------|------------|------------|
|
|
| 🏗️ Build Development | `./build.sh` | Builds `:dev` for active development |
|
|
| 🚀 Release | `./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. |
|
|
| 🧪 Dry Run | `./release.sh --dry-run <semver>` | Rehearse the release without pushing (optionally `--allow-dirty` for experimentation only) |
|
|
| 📦 Downstream | `FROM tsysdevstack-toolboxstack-toolbox-base:release-current` | Downstream Dockerfiles should inherit from `release-current` (or pin to a semantic tag for reproducibility) |
|
|
|
|
---
|
|
|
|
## 🧩 Tooling Inventory
|
|
|
|
### 🐚 Shells & Prompts
|
|
| 🛠️ Tool | 📋 Name | 📝 Notes |
|
|
|---------|---------|---------|
|
|
| 🐚 | `zsh` | Z shell with oh-my-zsh framework |
|
|
| 🐟 | `fish` | Friendly interactive shell |
|
|
| 🧑💻 | `bash` | Bourne again shell |
|
|
| ⭐ | `starship` | Cross-shell prompt |
|
|
| 💎 | `oh-my-zsh` | Zsh framework |
|
|
|
|
> ⭐ Starship prompt enabled for all shells; oh-my-zsh configured with `git` + `fzf` plugins.
|
|
|
|
### 🪄 Runtime & CLI Managers
|
|
| 🛠️ Tool | 📋 Name | 📝 Notes |
|
|
|---------|---------|---------|
|
|
| 🪄 | `mise` | Runtime manager for languages and tools |
|
|
| 💧 | `aqua` | CLI version manager |
|
|
|
|
> `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
|
|
| 🛠️ Tool | 📋 Name | 📝 Notes |
|
|
|---------|---------|---------|
|
|
| 📦 | `curl` | Command-line data transfer |
|
|
| 📥 | `wget` | Network downloader |
|
|
| 🔐 | `ca-certificates` | Common CA certificates |
|
|
| 🧭 | `git` | Distributed version control |
|
|
| 🔧 | `build-essential` | Essential build tools |
|
|
| 🔍 | `ripgrep` | Fast search tool |
|
|
| 🧭 | `fzf` | Fuzzy finder |
|
|
| 📁 | `fd` | Simple, fast & user-friendly alternative to find |
|
|
| 📖 | `bat` | Cat clone with syntax highlighting |
|
|
| 🔗 | `openssh-client` | OpenSSH client applications |
|
|
| 🧵 | `tmux` | Terminal multiplexer |
|
|
| 🖥️ | `screen` | Terminal multiplexer |
|
|
| 📈 | `htop` | Interactive process viewer |
|
|
| 📉 | `btop` | A monitor of resources |
|
|
| ♻️ | `entr` | Run arbitrary commands when files change |
|
|
| 📊 | `jq` | Command-line JSON processor |
|
|
| 🌐 | `httpie` | User-friendly curl replacement |
|
|
| ☕ | `tea` | Package manager for dev projects |
|
|
| 🧮 | `bc` | Arbitrary precision calculator language |
|
|
|
|
> Provides ergonomic defaults plus toolchain deps for compiling runtimes (no global language installs).
|
|
|
|
### 🌊 Aqua-Managed CLIs
|
|
| 🛠️ Tool | 📋 Name |
|
|
|---------|---------|
|
|
| 🐙 | `gh` (GitHub CLI) |
|
|
| 🌀 | `lazygit` |
|
|
| 🪄 | `direnv` |
|
|
| 🎨 | `git-delta` |
|
|
| 🧭 | `zoxide` |
|
|
| 🧰 | `just` |
|
|
| 🧾 | `yq` |
|
|
| ⚡ | `xh` |
|
|
| 🌍 | `curlie` |
|
|
| 🏠 | `chezmoi` |
|
|
| 🛠️ | `shfmt` |
|
|
| ✅ | `shellcheck` |
|
|
| 🐳 | `hadolint` |
|
|
| 🐍 | `uv` |
|
|
| 🔁 | `watchexec` |
|
|
|
|
> Extend via `~/.config/aquaproj-aqua/aqua.yaml`. These packages are baked into the image at build time for consistency and reproducibility. Direnv logging is muted and hooks for direnv/zoxide are pre-configured for zsh, bash, and fish.
|
|
|
|
### 🤖 AI CLI Tools
|
|
| 🛠️ Tool | 📋 Name |
|
|
|---------|---------|
|
|
| 🧠 | `@just-every/code` |
|
|
| 🤖 | `@qwen-code/qwen-code` |
|
|
| 💎 | `@google/gemini-cli` |
|
|
| 🔮 | `@openai/codex` |
|
|
| 🌐 | `opencode-ai` |
|
|
|
|
> AI-powered command-line tools for enhanced development workflows. Node.js is installed via mise to support npm package installation.
|
|
|
|
### 🐳 Container Workflow
|
|
| 🛠️ Feature | 📋 Description |
|
|
|------------|----------------|
|
|
| 🐳 | Docker socket mount (`/var/run/docker.sock`) - Enables Docker CLIs inside the container; host Docker daemon required. |
|
|
|
|
### 🧠 AI Tool Configuration
|
|
| 🛠️ Feature | 📋 Description |
|
|
|------------|----------------|
|
|
| 🧠 | Host directories for AI tools - Host directories for AI tool configuration and cache are mounted to maintain persistent settings and data across container runs. |
|
|
|
|
### 👤 Runtime Environment
|
|
| 🛠️ Feature | 📋 Description |
|
|
|------------|----------------|
|
|
| 👤 | Non-root user `toolbox` (UID/GID mapped) |
|
|
| 🗂️ | `/workspace` mount - Maintains host permissions and isolates artifacts under `artifacts/ToolboxStack/toolbox-base` |
|
|
|
|
---
|
|
|
|
## 🛠️ Extending the Sandbox
|
|
|
|
| 🧩 Task | 🛠️ Command | 📝 Description |
|
|
|---------|------------|----------------|
|
|
| 🧮 **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` | Extend the available tools in the environment |
|
|
| 🛠️ **Adjust base image** | Modify `Dockerfile`, run `./build.sh`, and keep this README & `PROMPT` in sync | Make changes to the base environment |
|
|
|
|
> 🔁 **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. 🏗️ **Build Test**: Run `./build.sh` and ensure it succeeds.
|
|
2. 🧪 **Functionality Test**: Optionally `./run.sh up` and sanity-check key tooling (e.g., `mise --version`, `gh --version`).
|
|
3. 📝 **Documentation Sync**: Update this README and the `PROMPT` with any new or removed tooling.
|
|
|
|
---
|
|
|
|
## 🤝 Collaboration Notes
|
|
|
|
| 📋 Best Practice | 📝 Description |
|
|
|------------------|----------------|
|
|
| 👤 **Non-Root Policy** | Container always runs as the mapped non-root user; avoid adding steps that require root login. |
|
|
| 🧩 **Tooling Consistency** | Prefer `mise`/`aqua` for new tooling to keep installations reproducible. |
|
|
| 📚 **Documentation Sync** | Keep documentation synchronized (README + PROMPT) so future contributors can resume quickly. |
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
See [LICENSE](../../LICENSE) for full terms.
|