Add Home

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 `<filesystem>` and `<fstream>` 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
+  <ports> <image> /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:<tag>` 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 <name> -f <outfile> .`).
+
+  ## 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.