From 11fa7168edb4317fdb860e94ff0589a0ed44efd4 Mon Sep 17 00:00:00 2001 From: markmental Date: Tue, 4 Nov 2025 15:26:20 +0000 Subject: [PATCH] Add Home --- Home.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 Home.md diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..e8cc24a --- /dev/null +++ b/Home.md @@ -0,0 +1,126 @@ + # Tux-Dock Wiki + + ## 1. Project Overview + Tux-Dock is a single-binary C++17 console application that wraps common Docker workflows in an interactive menu. + It serves as a lightweight abstraction layer that helps teams evolve “pet” containers into repeatable “cattle” + infrastructure: every ad-hoc shell action becomes a codified routine, nudging workflows toward production-grade + discipline. All menu actions shell out to the locally installed Docker Engine, so the tool behaves as a convenience + layer rather than a Docker API client. + + ## 2. Architecture & Design + - **Entry Point**: `main()` hosts an infinite menu loop and dispatches selections to `DockerManager`. + - **Core Class**: `DockerManager` encapsulates all Docker-facing routines. Each public method corresponds to a menu + option, keeping the CLI and behaviour in sync. + - **Command Execution**: All Docker calls are performed via `system()` or `popen()`. There is no additional parsing or + command templating layer. + - **State Handling**: The program remains stateless between operations. Container discovery is performed on demand + (`docker ps -a`) to keep menu choices current. + - **Filesystem Helpers**: The Dockerfile-generation feature relies on `` and `` to vet script + paths and stream file contents. + + ## 3. Build & Installation + | Step | Command | Notes | + | ---- | ------- | ----- | + | Compile | `./compile.sh` | Wraps `g++ -std=c++17 main.cpp -o tux-dock`. | + | Manual build | `g++ -std=c++17 main.cpp -o tux-dock` | Requires C++17-capable compiler. | + | Run | `sudo ./tux-dock` | Needs Docker privileges; add your user to the `docker` group to avoid `sudo`. | + + Dependencies: + - Docker Engine (tested on Debian 12/13, Alpine, Arch). + - Standard C++17 library (no third-party dependencies). + + ## 4. Menu Map + | Option | Description | Invoked Method | + | ------ | ----------- | -------------- | + | 1 | Pull an image by name/tag. | `DockerManager::pullImage` | + | 2 | Run/create interactive container with optional port mappings. | `runContainerInteractive` | + | 3 | List all containers (including stopped). | `listContainers` | + | 4 | List all local images. | `listImages` | + | 5 | Start a container and attach (`docker start -ai`). | `startInteractive` | + | 6 | Start a container in detached mode. | `startDetached` | + | 7 | Delete an image (`docker rmi`). | `deleteImage` | + | 8 | Stop a running container. | `stopContainer` | + | 9 | Remove a stopped container. | `removeContainer` | + | 10 | Attach an interactive shell to a running container. | `execShell` | + | 11 | Execute a command in detached mode. | `execDetachedCommand` | + | 12 | Launch a MySQL container with configurable port, password, version. | `spinUpMySQL` | + | 13 | Display the IP address of a container. | `showContainerIP` | + | 14 | Convert a bash script into a Dockerfile and optionally build an image. | `createDockerfile` | + | 15 | Exit the program. | — | + + ## 5. Key Workflows + + ### 5.1 Container Selection + - The helper `selectContainer()` lists containers with a numbering scheme derived from `docker ps -a --format '{{.ID}} + {{.Names}}'`. + - Users choose by number; the function returns the full container ID for downstream commands. + - Invalid selections or empty lists short-circuit the requested action. + + ### 5.2 Running Containers + - Option 2 prompts for an image, desired port mappings, and explains the `-p` syntax before calling `docker run -it + /bin/sh`. + - The shell defaults to `/bin/sh`. If the image lacks `/bin/sh`, the command will fail—users should supply images + accordingly. + + ### 5.3 Detached Commands + - Option 11 accepts a free-form command via `getline`. Quotes (`"`) and backslashes (`\`) are escaped before + constructing `docker exec -d`. + - Whitespace and other shell-sensitive characters are passed through, so complex commands might require additional + manual quoting. + + ### 5.4 MySQL Bootstrap + - Option 12 wraps `docker run -d mysql:` with required environment variables and port mapping. + - The container name defaults to `mysql-container`; repeated runs must stop/remove the existing container first or be + renamed manually. + + ### 5.5 Dockerfile Generator + - Reads a bash script line by line, skipping empty lines and comments. + - Outputs a Dockerfile with a `FROM` line, sets `/app` as `WORKDIR`, and converts each remaining line into a `RUN` + directive. + - Appends `CMD ["/bin/bash"]` to keep the container interactive by default. + - Optionally builds an image immediately (`docker build -t -f .`). + + ## 6. Extending Tux-Dock + + 1. **Add a Menu Entry**: Insert a new case in the `switch` statement and expose a corresponding public method on + `DockerManager`. + 2. **Implement Docker Logic**: Follow existing patterns—call `runCommand()` for straightforward shell commands or + `popen()` if output must be parsed. + 3. **User Prompts**: Prefer structured prompts (`cin >> value`) for simple inputs; switch to `getline()` when spaces + are expected (remember to flush `cin` beforehand). + 4. **Validation**: Add additional validation or confirmation where commands could be destructive (e.g., bulk removes, + pruning). + 5. **Documentation**: Update this wiki and the README with new functionality and edge cases. + + Suggested enhancements: + - Add `docker logs`, `docker stats`, and image pruning commands. + - Swap `system()` for `std::system` alternatives or libdocker bindings if stronger security or portability is + required. + - Introduce configuration files for default images, port mappings, and container names. + + ## 7. Security & Operational Considerations + - **Input Sanitisation**: User inputs feed directly into shell commands. Avoid untrusted usage or wrap commands with + additional validation when integrating into shared environments. + - **Shell Assumptions**: Hard-coded `/bin/sh` may fail on minimal images (e.g., Scratch). Allow configurable shells + for broader compatibility. + - **Error Handling**: Most commands simply echo Docker output. Enhance detection for non-zero exit codes to deliver + clearer feedback. + - **Permissions**: Docker commands require either root privileges or membership in the `docker` group. Documented in + README and reiterated here. + - **Log Handling**: The app prints Docker CLI output to stdout; there is no logging subsystem. + + ## 8. Troubleshooting + | Symptom | Likely Cause | Mitigation | + | --- | --- | --- | + | “command not found” | Docker CLI missing or not in PATH. | Install Docker or ensure the binary is accessible. | + | Menu inputs skipped | Mixing `cin >>` and `getline` without flushing. | Already handled before `getline`, but ensure + custom additions call `cin.ignore()` appropriately. | + | MySQL launch fails | Existing container named `mysql-container`, wrong port, or incompatible tag. | Remove/rename + conflicting containers; verify credentials. | + | Dockerfile build errors | Bash script contains multi-line constructs or unsupported commands. | Refine script or + manually edit generated Dockerfile. | + + ## 9. Related Assets + - `compile.sh`: Convenience build script for the binary. + - `option13_script.sh`: Example bash script suitable for the Dockerfile generator demo. + - README: Marketing-ready overview; keep wiki and README aligned to avoid drift. \ No newline at end of file