dockbub

DockBub 🐳

A beautiful, comprehensive Docker management TUI (Terminal User Interface) built with Bubble Tea

DockBub provides an intuitive, keyboard-driven interface for managing all aspects of Docker - containers, images, volumes, networks, and Docker Compose - right from your terminal.

Features

🐋 Container Management

• List & Monitor: View all containers (running, stopped) with real-time status updates
• Control Operations: Start, stop, restart, pause, unpause containers
• Logs Viewer: View container logs with follow mode support (press 'f' to toggle follow)
• Real-time Stats: Monitor CPU usage, memory, network I/O, disk I/O, and PIDs in real-time
• Inspection: Detailed container information and configuration
• Interactive Shell: Execute interactive shells (/bin/bash or /bin/sh) in running containers
• Cleanup: Remove containers with force option support

🖼️ Image Management

• Browse Images: List all images with size, tags, and creation date
• Pull & Push: Pull images from registries and push to remote repositories
• Build Images: Build images from Dockerfile
• Tag Management: Tag and untag images
• Image History: View image layers and history
• Prune: Remove unused images to free up disk space

💾 Volume Management

• List Volumes: View all Docker volumes with driver and mountpoint information
• Create & Remove: Create new volumes and remove unused ones
• Inspect Details: View detailed volume configuration
• Prune: Clean up unused volumes

🌐 Network Management

• List Networks: View all Docker networks with driver and scope
• Create Networks: Create custom networks with specified drivers
• Container Connectivity: Connect and disconnect containers to/from networks
• Network Inspection: View detailed network configuration

🐙 Docker Compose Support

• List Projects: Automatically detect and list all running Docker Compose projects
• Project Management: View projects with their services, status, and configuration paths
• File Viewer: View actual docker-compose.yml/yaml files with syntax highlighting and line numbers
• Service Control: Start, stop, restart individual services or entire projects
• Multi-Select Mode: Select multiple services for batch operations (start, stop, restart, build, pull, push)
• Search/Filter: Filter projects by name, path, or status with real-time search
• Operations: Full support for up, down, restart, build, pull, push commands
• Progress Tracking: Real-time progress indicators for build, pull, and push operations
• Logs Viewer: View logs from individual services or entire projects
• Real-time Status: Monitor service health and container status
• Scale Services: Scale services to specified number of replicas

📊 System Operations

• System Information: View Docker daemon info, version, and configuration
• Disk Usage Analysis: Monitor storage usage by containers, images, and volumes
• Resource Statistics: CPU, memory, and system resource monitoring
• System Prune: Clean up all unused Docker resources
• Real-time Events: Monitor Docker events as they happen

Installation

Prerequisites

• Docker: Make sure Docker is installed and running on your system
• Go 1.21+: Required for building from source

Build from Source

# Clone the repository
git clone https://github.com/TechHutTV/dockbub.git
cd dockbub

# Build the binary
go build -o dockbub ./cmd/dockbub

# Optionally, move to your PATH
sudo mv dockbub /usr/local/bin/

# Run DockBub
dockbub

Quick Install

# One-liner to build and install
go install github.com/TechHutTV/dockbub/cmd/dockbub@latest

Usage

Simply run the binary:

dockbub

DockBub will automatically connect to your Docker daemon (via Unix socket or TCP).

Docker Connection

DockBub uses the Docker SDK and respects standard Docker environment variables:

• DOCKER_HOST: Docker daemon socket/TCP address
• DOCKER_API_VERSION: Specific API version to use
• DOCKER_CERT_PATH: Path to TLS certificates
• DOCKER_TLS_VERIFY: Enable TLS verification

Keybindings

Global Navigation

Key	Action
Tab / Shift+Tab	Switch between tabs
↑ / ↓ / j / k	Navigate up/down in lists
← / → / h / l	Navigate left/right
Home	Jump to first item
End	Jump to last item
Enter	Select/Execute action
Esc	Go back/Cancel
? / F1	Toggle help overlay
q / Ctrl+C	Quit application
/	Search/Filter (in Compose view)

Container Operations

Key	Action
s	Start container
x	Stop container
r	Restart container
p	Pause container
u	Unpause container
l	View logs (press 'f' to toggle follow mode)
i	Inspect details
t	View stats (real-time CPU, memory, network, disk I/O)
e	Execute shell
d	Delete container
a	Toggle show all containers

Image Operations

Key	Action
p	Pull image
b	Build image
t	Tag image
P	Push image (uppercase P)
d	Delete image
h	View history
i	Inspect details
P (uppercase)	Prune unused images

Volume Operations

Key	Action
c	Create volume
i	Inspect details
d	Delete volume
p	Prune unused volumes

Network Operations

Key	Action
c	Create network
i	Inspect details
n	Connect container to network
N	Disconnect container (uppercase N)
d	Delete network

Compose Operations

Project List View

Key	Action
Enter / i	View project services
v	View compose file (docker-compose.yml)
/	Search/Filter projects
u	Up (start project/services)
d	Down (stop project - requires confirmation)
r	Restart project/services
b	Build services
p	Pull service images
Esc	Clear search filter

Services View

Key	Action
m	Toggle multi-select mode
Space	Toggle service selection (in multi-select mode)
l	View service logs
r	Restart service(s)
s	Stop service(s)
S	Start service(s) (uppercase S)
b	Build service(s) with progress
p	Pull service(s) images with progress
P	Push service(s) images with progress (uppercase P)
Esc	Exit multi-select or go back to projects list

System Operations

Key	Action
r	Refresh system info
p	Prune system (cleanup)
e	View events

UI Design

DockBub features a beautiful, intuitive interface with:

• Color-coded Status Indicators:

  • 🟢 Green: Running containers
  • 🔴 Red: Stopped/exited containers
  • 🟡 Yellow: Paused containers
  • 🔵 Blue: Informational items

• Split-pane Layout: Navigation sidebar and main content area

• Status Bar: Shows Docker daemon status, version, and real-time clock

• Command Bar: Context-sensitive keybinding hints at the bottom

• Tab Navigation: Easy switching between different resource types

• Confirmation Dialogs: Safety prompts for destructive operations

• Real-time Updates: Auto-refresh every 2 seconds

• Responsive Design: Adapts to terminal size

Architecture

dockbub/
├── cmd/dockbub/          # Main application entry point
├── internal/
│   ├── docker/           # Docker SDK wrapper and client
│   ├── models/           # Data models and types
│   ├── ui/               # Bubble Tea UI components
│   │   ├── components/   # Reusable UI components
│   │   ├── styles/       # Lipgloss styles and themes
│   │   └── views/        # Tab views (containers, images, etc.)
│   └── config/           # Configuration management
├── examples/             # Example files and demos
└── docs/                 # Documentation

Technology Stack

• Bubble Tea: The TUI framework (Elm architecture)
• Lipgloss: Terminal styling and layout
• Docker SDK for Go: Official Docker API client
• Go 1.21+: Modern, fast, and reliable

Configuration

DockBub can be configured via ~/.config/dockbub/config.yaml (coming soon):

# Refresh interval in seconds
refresh_interval: 2

# Color theme
theme: default  # default, dracula, nord, monokai

# Default view on startup
default_tab: containers  # containers, images, volumes, networks, compose, system

# Show all containers by default
show_all_containers: true

# Docker connection
docker:
  host: unix:///var/run/docker.sock
  api_version: "1.41"
  tls_verify: false

Troubleshooting

Cannot connect to Docker daemon

Make sure Docker is running and your user has permission to access the Docker socket:

# Check if Docker is running
docker ps

# Add your user to the docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

Permission denied

# Make the binary executable
chmod +x dockbub

Binary not found

Make sure /usr/local/bin is in your PATH:

echo $PATH
export PATH=$PATH:/usr/local/bin

Development

Building

go build -o dockbub ./cmd/dockbub

Running

./dockbub

Testing

go test ./...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Roadmap

• Container management (list, start, stop, restart, remove)
• Image management (list, pull, build, remove, prune)
• Volume management (list, create, remove, prune)
• Network management (list, create, remove, connect)
• System information and disk usage
• Beautiful TUI with Lipgloss styling
• Keyboard navigation and shortcuts
• Confirmation dialogs for destructive actions
• Container logs viewer with follow mode
• Container stats (real-time CPU, memory, network, disk I/O)
• Interactive shell execution in containers
• Docker Compose full integration (list projects, manage services, logs, scale)
• Compose file viewer with line numbers
• Image build from Dockerfile with progress
• Image push/pull with progress bars
• Multi-select for batch operations on Compose services
• Search/filter functionality for Compose projects
• Configuration file support
• Custom themes
• Bookmarks/favorites
• Export/import functionality
• Docker registry browser
• Statistics graphs
• Resource limit warnings
• Quick actions menu (Ctrl+P)
• Nano-style text editor for compose files
• Real-time Docker events viewer

License

MIT License - see LICENSE file for details

Acknowledgments

• Charm for the amazing Bubble Tea framework and Lipgloss
• Docker for their excellent API and SDK
• The Go community for building great tools

Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• ⭐ Star this repo if you find it useful!

---

Made with ❤️ using Go and Bubble Tea