Tux-Dock

A lightweight C++ Docker TUI

Tux-Dock is a modern C++17 Docker terminal frontend built with FTXUI. It gives you a guided, keyboard-first TUI for common Docker operations without memorizing long CLI flags.

---

Features

• Interactive Docker workflows through a single-screen TUI with modal steps.
• Picker-based selection (arrow keys + Enter) for containers/images instead of numeric menus.
• Busy-operation modals with a spinner and input blocking while Docker work completes.
• Rich container display with state and forwarded ports.
• Interactive shell handoff with clean terminal clear before/after shell transitions.
• Image operations: pull/list/delete with curated quick picks and custom image support.
• Script-to-image workflow: generate Dockerfile from bash script, then optionally build.
• MySQL quick start flow with version/password/port prompts.
• Docker Engine API access through /var/run/docker.sock for structured list and lifecycle operations.
• Direct fork/exec process execution for CLI-backed streaming and interactive commands.
• Persistent container listings that retain exited containers.
• Robust stop handling with state polling, timeout retry, and idempotent stop responses.
• About screen in-app with project/version/repository info.

---

Build Requirements

• C++17 or newer compiler (e.g. g++, clang++)
• CMake 3.16+
• Docker Engine installed and running

---

Build & Run

# Clone the repo
git clone https://mentalnet.xyz/forgejo/markmental/tuxdock.git
cd tuxdock

# Configure, build, and test (FTXUI and nlohmann/json are fetched automatically)
./compile.sh

# Run it (requires Docker permissions)
sudo ./build/tux-dock

# Build without running tests
./compile.sh --no-test

Prefer a prebuilt binary? CI artifacts are published at: https://mentalnet.xyz/forgejo/markmental/tuxdock/actions

---

Menu Overview

Current TUI actions:

1. Pull Docker Image
2. Run/Create Interactive Container
3. List All Containers
4. List All Images
5. Start Container Interactively (boot new session)
6. Start Detached Container Session
7. Delete Docker Image
8. Stop Container
9. Remove Container
10. Attach Shell to Running Container
11. Run Detached Command in Container
12. Spin Up MySQL Container
13. Create Dockerfile & Build Image from Bash Script
14. About Tux-Dock
15. Exit

---

Design Overview

Tux-Dock is organized around the TUI, Docker manager, Engine API client, and direct process runner:

class DockerManager {
public:
  struct ContainerInfo {
    std::string id;
    std::string name;
    std::string status;
    std::string ports;
    bool running;
  };

  bool checkConnection(...);
  ListResult<ContainerInfo> getContainerList() const;
  ListResult<ImageInfo> getImageList() const;
  bool pullImage(...);
  bool runContainerInteractive(...);
  bool startInteractive(...);
  bool startDetached(...);
  bool stopContainer(...);
  bool removeContainer(...);
  bool deleteImage(...);
  bool execShell(...);
  bool execDetachedCommand(...);
  bool spinUpMySQL(...);
  bool createDockerfile(...);
};

class TuxDockApp {
public:
  void Run();

private:
  // TUI orchestration layer with modal busy states
  void OpenInput(...);
  void OpenSelect(...);
  void OpenConfirm(...);
  void BeginBusyOperation(...);
  void RunWithRestoredIO(...);
  void ExecuteSelectedAction();
  // action handlers bridge UI -> DockerManager
};

Responsibilities

• DockerEngineClient

  • Talks directly to Docker over the Unix socket.
  • Parses HTTP responses, including chunked and bodyless responses.

• ProcessRunner

  • Executes direct argument vectors using fork and exec.
  • Supports captured output and inherited terminal I/O.

• DockerManager

  • Maps Engine API JSON into application data.
  • Performs lifecycle operations and robust stop-state confirmation.
  • Preserves cached state when refreshes fail.

• TuxDockApp

  • Renders the FTXUI interface.
  • Manages modal flows (input/select/confirm/message).
  • Handles modal flows, busy operations, blocked input, and interactive shell transitions.
  • Coordinates end-to-end user flows by calling DockerManager methods.

This split keeps Docker behavior isolated while making UI behavior easier to extend.

---

Testing

cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build -j
ctest --test-dir build --output-on-failure

compile.sh runs these tests by default. Pass --no-test to skip them.

---

About / Version

• Version: 0.1-beta
• Created by: markmental
• GitHub: https://github.com/MARKMENTAL/tuxdock
• Forgejo: https://mentalnet.xyz/forgejo/markmental/tuxdock

---

License

MIT License — free to use, modify, and share.