This commit is contained in:
parent
c818c5bfbe
commit
ba7130db9f
1 changed files with 89 additions and 116 deletions
205
README.md
205
README.md
|
|
@ -1,36 +1,34 @@
|
||||||
# 🐧 Tux-Dock
|
# Tux-Dock
|
||||||
### A lightweight C++ Docker management CLI
|
### A lightweight C++ Docker TUI
|
||||||
|
|
||||||
Tux-Dock is a simple, modern, and fast **C++17** command-line utility for managing Docker containers and images.
|
Tux-Dock is a modern **C++17** Docker terminal frontend built with **FTXUI**.
|
||||||
It offers a clean, interactive menu for common Docker operations like pulling images, running containers, and inspecting IP addresses — without the overhead of complex GUIs or scripts.
|
It gives you a guided, keyboard-first TUI for common Docker operations like pulling images, running containers, inspecting IPs, and managing images/containers without memorizing long CLI flags.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ✨ Features
|
## Features
|
||||||
|
|
||||||
- 🔹 **Interactive container management** — start, stop, remove, or attach to containers with simple numbered menus.
|
- Interactive Docker workflows through a single-screen TUI with modal steps.
|
||||||
- 🔹 **Port mapping made clear** — automatically prompts for and explains host ↔ container port bindings.
|
- Picker-based selection (arrow keys + Enter) for containers/images instead of numeric menus.
|
||||||
- 🔹 **Image operations** — pull, list, and delete Docker images; curated pull list (Debian, Ubuntu, Rocky Linux, Alpine) plus a custom entry to grab common bases without retyping them.
|
- High-level status panel with responsive wait states for slower operations.
|
||||||
- 🔹 **Script-to-image workflow** — turn a bash setup script into a Dockerfile and build the resulting image in one go.
|
- Rich container display with state and forwarded ports.
|
||||||
- 🔹 **Quick MySQL setup** — spin up a MySQL container with version, password, and port configuration in seconds.
|
- Interactive shell handoff with clean terminal clear before/after shell transitions.
|
||||||
- 🔹 **Get container IP address** — cleanly retrieves and displays only the container’s assigned IP.
|
- Image operations: pull/list/delete with curated quick picks and custom image support.
|
||||||
- 🔹 **Run detached commands** — execute background jobs inside a container without attaching an interactive shell.
|
- Script-to-image workflow: generate Dockerfile from bash script, then optionally build.
|
||||||
- 🔹 **Modern C++ design** — built with classes, minimal dependencies, and clear abstractions.
|
- MySQL quick start flow with version/password/port prompts.
|
||||||
- 🔹 **Interactive run flow** — lists pulled images with numeric selection, allows entering a custom image name, and keeps the port-mapping explanation in place before launching `/bin/sh`.
|
- About screen in-app with project/version/repository info.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🧩 Build Requirements
|
## Build Requirements
|
||||||
|
|
||||||
- **C++17 or newer** compiler
|
- **C++17 or newer** compiler (e.g. `g++`, `clang++`)
|
||||||
(e.g., `g++`, `clang++`)
|
|
||||||
- **CMake 3.16+**
|
- **CMake 3.16+**
|
||||||
- **Docker Engine** installed and running
|
- **Docker Engine** installed and running
|
||||||
(tested on Debian 12/13, Alpine Linux, and Arch Linux)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ⚙️ Build & Run
|
## Build & Run
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repo
|
# Clone the repo
|
||||||
|
|
@ -45,133 +43,108 @@ cmake --build build -j
|
||||||
sudo ./build/tux-dock
|
sudo ./build/tux-dock
|
||||||
```
|
```
|
||||||
|
|
||||||
Prefer a prebuilt binary? The CI runner publishes build artifacts for the latest commits at:
|
Prefer a prebuilt binary? CI artifacts are published at:
|
||||||
https://mentalnet.xyz/forgejo/markmental/tuxdock/actions
|
https://mentalnet.xyz/forgejo/markmental/tuxdock/actions
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🖥️ Menu Overview
|
## Menu Overview
|
||||||
|
|
||||||
```
|
Current TUI actions:
|
||||||
Tux-Dock: Docker Management Menu
|
|
||||||
----------------------------------
|
1. Pull Docker Image
|
||||||
1. Pull Docker Image
|
2. Run/Create Interactive Container
|
||||||
2. Run/Create Interactive Container
|
3. List All Containers
|
||||||
3. List All Containers
|
4. List All Images
|
||||||
4. List All Images
|
5. Start Container Interactively (boot new session)
|
||||||
5. Start Container Interactively (boot new session)
|
6. Start Detached Container Session
|
||||||
6. Start Detached Container Session
|
7. Delete Docker Image
|
||||||
7. Delete Docker Image
|
8. Stop Container
|
||||||
8. Stop Container
|
9. Remove Container
|
||||||
9. Remove Container
|
|
||||||
10. Attach Shell to Running Container
|
10. Attach Shell to Running Container
|
||||||
11. Run Detached Command in Container
|
11. Run Detached Command in Container
|
||||||
12. Spin Up MySQL Container
|
12. Spin Up MySQL Container
|
||||||
13. Get Container IP Address
|
13. Get Container IP Address
|
||||||
14. Create Dockerfile & Build Image from Bash Script
|
14. Create Dockerfile & Build Image from Bash Script
|
||||||
15. Exit
|
15. About Tux-Dock
|
||||||
```
|
16. Exit
|
||||||
|
|
||||||
Each action guides you through the required steps.
|
|
||||||
For container-related commands, Tux-Dock automatically lists available containers and lets you choose by **number**, not by typing long IDs.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📡 Example: Getting a Container’s IP Address
|
## Design Overview
|
||||||
|
|
||||||
```
|
Tux-Dock is now structured around **two main classes**:
|
||||||
Available Containers:
|
|
||||||
1. mysql-container (ebaf5dbae393)
|
|
||||||
2. webapp (fa29b6c1f1e8)
|
|
||||||
|
|
||||||
Select container to view IP (1-2): 2
|
|
||||||
Container IP Address: 172.17.0.3
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧱 Design Overview
|
|
||||||
|
|
||||||
Tux-Dock is built using a single class:
|
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
class DockerManager {
|
class DockerManager {
|
||||||
public:
|
public:
|
||||||
void pullImage();
|
struct ContainerInfo {
|
||||||
void runContainerInteractive();
|
std::string id;
|
||||||
void listContainers() const;
|
std::string name;
|
||||||
void listImages() const;
|
std::string status;
|
||||||
void startInteractive();
|
std::string ports;
|
||||||
void startDetached();
|
bool running;
|
||||||
void deleteImage();
|
};
|
||||||
void stopContainer();
|
|
||||||
void removeContainer();
|
// Docker command/data layer
|
||||||
void execShell();
|
std::vector<ContainerInfo> getContainerList() const;
|
||||||
void execDetachedCommand();
|
std::vector<std::pair<std::string, std::string>> getImageList() const;
|
||||||
void createDockerfile();
|
bool pullImage(...);
|
||||||
void spinUpMySQL();
|
bool runContainerInteractive(...);
|
||||||
void showContainerIP();
|
bool startInteractive(...);
|
||||||
|
bool startDetached(...);
|
||||||
|
bool stopContainer(...);
|
||||||
|
bool removeContainer(...);
|
||||||
|
bool deleteImage(...);
|
||||||
|
bool execShell(...);
|
||||||
|
bool execDetachedCommand(...);
|
||||||
|
bool spinUpMySQL(...);
|
||||||
|
bool showContainerIP(...);
|
||||||
|
bool createDockerfile(...);
|
||||||
|
};
|
||||||
|
|
||||||
|
class TuxDockApp {
|
||||||
|
public:
|
||||||
|
void Run();
|
||||||
|
|
||||||
private:
|
private:
|
||||||
static void runCommand(const std::string& cmd);
|
// TUI orchestration layer
|
||||||
std::vector<std::pair<std::string, std::string>> getContainerList() const;
|
void OpenInput(...);
|
||||||
std::string selectContainer(const std::string& prompt);
|
void OpenSelect(...);
|
||||||
/* NEW helper – retrieves all images */
|
void OpenConfirm(...);
|
||||||
std::vector<std::pair<std::string, std::string>> getImageList() const;
|
void RunDeferredStatusAction(...);
|
||||||
|
void RunWithRestoredIO(...);
|
||||||
|
void ExecuteSelectedAction();
|
||||||
|
// action handlers bridge UI -> DockerManager
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
### Method Reference
|
### Responsibilities
|
||||||
- `pullImage` — prompt for an image name and run `docker pull`.
|
|
||||||
- `runContainerInteractive` — configure port mappings and start a new interactive container session.
|
|
||||||
- `listContainers` — show all Docker containers (running or stopped).
|
|
||||||
- `listImages` — list local Docker images.
|
|
||||||
- `startInteractive` — start an existing container and attach a shell.
|
|
||||||
- `startDetached` — start an existing container in detached mode.
|
|
||||||
- `deleteImage` — remove a local Docker image.
|
|
||||||
- `stopContainer` — stop a running container.
|
|
||||||
- `removeContainer` — delete a container after confirmation.
|
|
||||||
- `execShell` — attach a shell to a running container.
|
|
||||||
- `execDetachedCommand` — run a background command inside a container.
|
|
||||||
- `createDockerfile` — turn a bash script into a Dockerfile and build an image.
|
|
||||||
- `spinUpMySQL` — launch a MySQL container with custom port, password, and version.
|
|
||||||
- `showContainerIP` — display a container’s IP address.
|
|
||||||
- `runCommand` — helper to invoke shell commands.
|
|
||||||
- `getContainerList` — retrieve Docker container IDs and names for selection menus.
|
|
||||||
- `getImageList` — gather local Docker image IDs and names for menus and reporting.
|
|
||||||
- `selectContainer` — present a menu to pick a container interactively.
|
|
||||||
|
|
||||||
This makes the codebase **extensible** — adding new Docker features like `docker logs` or `docker stats` requires only a small new method.
|
- `DockerManager`
|
||||||
|
- Executes Docker commands.
|
||||||
|
- Escapes shell arguments and returns success/failure + user-facing messages.
|
||||||
|
- Collects container/image data used by the UI.
|
||||||
|
|
||||||
|
- `TuxDockApp`
|
||||||
|
- Renders the FTXUI interface.
|
||||||
|
- Manages modal flows (input/select/confirm/message).
|
||||||
|
- Handles status updates, deferred actions, 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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🧠 Why C++?
|
## About / Version
|
||||||
|
|
||||||
C++ was one of my formative languages when I was learning to program — it’s where I first grasped core concepts like memory management, data structures, OOP and abstraction.
|
- Version: `022526-dev`
|
||||||
Writing Tux-Dock in C++ is both nostalgic and practical: it combines the clarity of modern design with the raw performance and control that first inspired me to code.
|
- Created by: `markmental`
|
||||||
|
- GitHub: https://github.com/MARKMENTAL/tuxdock
|
||||||
|
- Forgejo: https://mentalnet.xyz/forgejo/markmental/tuxdock
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📜 License
|
## License
|
||||||
|
|
||||||
MIT License — free to use, modify, and share.
|
MIT License — free to use, modify, and share.
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 💡 Tip
|
|
||||||
|
|
||||||
If you’d like Tux-Dock to run without `sudo`, add your user to the Docker group:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo usermod -aG docker $USER
|
|
||||||
```
|
|
||||||
|
|
||||||
Then log out and back in.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Author:** MARKMENTAL
|
|
||||||
**Project:** Tux-Dock — *A clean and modern CLI for Docker power users.*
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue