KNEL/TSYSDevStack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: beautify all documentation files with icons, tables, and improved formatting

Browse Source 
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
This commit is contained in:
Charles N Wyble - admin
2025-10-31 15:06:41 -05:00
parent becd640c86
commit 3ec443eef8
5 changed files with 410 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
ToolboxStack/output/toolbox-base/README.md
View File

@@ -1,64 +1,138 @@
# 🧰 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
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
```
| 📋 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 |
The compose service mounts the current repo to `/workspace` (read/write) and runs as the mapped host user (`toolbox`).
> **💡 Note:** 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).
| 🛠️ 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
| 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`. 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** | 🧠 `@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** | 🐳 Docker socket mount (`/var/run/docker.sock`) | Enables Docker CLIs inside the container; host Docker daemon required. |
| **AI Tool Configuration** | 🧠 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** | 👤 Non-root user `toolbox` (UID/GID mapped) • 🗂️ `/workspace` mount | Maintains host permissions and isolates artifacts under `artifacts/ToolboxStack/toolbox-base`. |
### 🐚 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
- **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.
| 🧩 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.
@@ -66,8 +140,8 @@ The compose service mounts the current repo to `/workspace` (read/write) and run
## 📂 Project Layout
| Path | Purpose |
|------|---------|
| 📁 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. |
@@ -81,14 +155,23 @@ The compose service mounts the current repo to `/workspace` (read/write) and run
## ✅ 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.
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
- 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.
| 📋 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.

139
ToolboxStack/output/toolbox-qadocker/README.md
View File

@@ -1,45 +1,61 @@
# Toolbox-QADocker
# 🔍 Toolbox-QADocker
> **Docker Image Auditing & Quality Assurance**
Toolbox-QADocker is a specialized Docker image designed for auditing and quality assurance of Docker images and related files. It serves as the bootstrap image that audits the toolbox-base and other custom toolboxes in the TSYSDevStack ecosystem.
## Purpose
---
- **Docker Image Auditing**: Equipped with tools like Hadolint, Dive, and Trivy for comprehensive Docker image analysis
- **Shell Script Validation**: Includes ShellCheck for validating shell scripts
- **Bootstrap Tool**: Used to audit the base and other custom toolboxes during development
- **Quick Rebuilds**: Designed to be minimal and quick to rebuild when needed
## 🎯 Purpose
## Tools Included
| 🧰 Feature | 📋 Description |
|------------|----------------|
| 🔍 **Docker Image Auditing** | Equipped with tools like Hadolint, Dive, and Trivy for comprehensive Docker image analysis |
| 📜 **Shell Script Validation** | Includes ShellCheck for validating shell scripts |
| 🔁 **Bootstrap Tool** | Used to audit the base and other custom toolboxes during development |
| ⚡ **Quick Rebuilds** | Designed to be minimal and quick to rebuild when needed |
- **Hadolint**: Dockerfile linter that checks for best practices
- **ShellCheck**: Static analysis tool for shell scripts
- **Trivy**: Comprehensive vulnerability scanner for containers
- **Docker Client**: Command-line interface for Docker
- **Dive**: Tool to explore layers in Docker images
- **Buildctl**: BuildKit client for advanced builds
- **Dockerlint**: Additional Dockerfile linter
- **Node.js**: JavaScript runtime for additional tooling
---
## Image Details
## 🛠️ Tools Included
- Built from Ubuntu 24.04 base image
- Does NOT use the toolbox-base as foundation (unlike other toolboxes)
- Contains a non-root user `qadocker` for security
- Optimized for fast rebuilds and audits
| 🛠️ Tool | 📝 Description |
|---------|----------------|
| 🐳 **[Hadolint](https://github.com/hadolint/hadolint)** | Dockerfile linter that checks for best practices |
| 🐚 **[ShellCheck](https://www.shellcheck.net/)** | Static analysis tool for shell scripts |
| 🛡️ **[Trivy](https://github.com/aquasecurity/trivy)** | Comprehensive vulnerability scanner for containers |
| 🐳 **Docker Client** | Command-line interface for Docker |
| 🔍 **[Dive](https://github.com/wagoodman/dive)** | Tool to explore layers in Docker images |
| 🏗️ **Buildctl** | BuildKit client for advanced builds |
| 🐳 **[Dockerlint](https://github.com/RedCoolBeans/dockerlint)** | Additional Dockerfile linter |
| 🟨 **[Node.js](https://nodejs.org/)** | JavaScript runtime for additional tooling |
## Usage
---
### Build the Image
## 📊 Image Details
| 🧩 Aspect | 📌 Value |
|-----------|----------|
| 🏗️ **Base Image** | Ubuntu 24.04 |
| 🔐 **Foundation** | Does NOT use the toolbox-base as foundation (unlike other toolboxes) |
| 👤 **Non-Root User** | Contains a non-root user `qadocker` for security |
| ⚡ **Optimization** | Optimized for fast rebuilds and audits |
---
## 🚀 Usage
### 🏗️ Build the Image
```bash
./build.sh
```
### Run the Container Interactively
### 🖥️ Run the Container Interactively
```bash
./run.sh
```
### Run Directly with Docker
### 🐳 Run Directly with Docker
```bash
docker run -it --rm \
-v "$(pwd)":/workspace \
@@ -48,35 +64,76 @@ docker run -it --rm \
bash
```
### Run QA on a Dockerfile
### 🔍 Run QA on a Dockerfile
```bash
docker run --rm -v /path/to/project:/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev hadolint --config .hadolint.yaml Dockerfile
```
### Run QA on Shell Scripts
### 🐚 Run QA on Shell Scripts
```bash
docker run --rm -v /path/to/project:/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck script.sh
```
## Non-Root User
### 📊 Run Comprehensive Audit
```bash
# Using the custom audit script
docker run --rm -v /path/to/project:/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev bash -c "./audit-dockerfile.sh Dockerfile"
```
The container runs as the `qadocker` user by default. If you need root access, run the container with `--user root`.
---
## Security
## 👤 Non-Root User
- Built with security best practices in mind
- Minimal attack surface
- Non-root user for running tools
- Regular security scanning with Trivy
- 🏃‍♂️ The container runs as the `qadocker` user by default
- 🛡️ For security purposes, this reduces attack surface
- 🧑‍💻 If you need root access, run the container with `--user root`
## Development
---
This image is designed to be simple to modify and rebuild. The Dockerfile contains all necessary tool installations and is optimized for caching and build speed.
## 🔒 Security
## QA Process
| 🔒 Security Aspect | 📋 Details |
|-------------------|------------|
| 🛡️ **Best Practices** | Built with security best practices in mind |
| 🔓 **Attack Surface** | Minimal attack surface |
| 👤 **User Privileges** | Non-root user for running tools |
| 🛡️ **Scanning** | Regular security scanning with Trivy |
The image QA process includes:
- Validating the Dockerfile with Hadolint
- Checking shell scripts with ShellCheck
- Running filesystem scans with Trivy
- Verifying all tools are properly installed
---
## 🛠️ Development
- 🧩 This image is designed to be simple to modify and rebuild
- 🧱 The Dockerfile contains all necessary tool installations
- 🚀 Optimized for caching and build speed
- 🧪 Includes custom audit scripts for Dockerfile best practices
---
## 🔍 QA Process
| ✅ QA Step | 📝 Description |
|------------|----------------|
| 🐳 **Hadolint Validation** | Validating the Dockerfile with Hadolint |
| 🐚 **ShellCheck** | Checking shell scripts with ShellCheck |
| 🛡️ **Trivy Scan** | Running filesystem scans with Trivy |
| 🧪 **Tool Verification** | Verifying all tools are properly installed |
| 📊 **Custom Audit** | Using custom scripts to check for best practices |
---
## 📈 Audit Capabilities
Toolbox-QADocker excels at identifying:
- ❌ **Security Issues**: Common vulnerabilities and misconfigurations
- ⚙️ **Best Practices**: Adherence to Dockerfile best practices
- 🔒 **Root Usage**: Minimizing root operations in Docker builds
- 🚀 **Optimization**: Layer efficiency and image size optimization
- 🛡️ **Configuration Issues**: Potential security misconfigurations
---
## 📄 License
See [LICENSE](../../LICENSE) for full terms.