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.

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.