dtop - Docker Terminal UI

A high-performance terminal UI for Docker container management with real-time monitoring, advanced log viewing, and comprehensive container operations.

Features

🚀 Core Functionality

• Real-time Monitoring: Live CPU, memory, network, and disk I/O stats with parallel collection
• Container Management: Complete lifecycle control (start, stop, pause, restart, recreate)
• Interactive Shell Access: Direct exec into containers with terminal support
• Resource Monitoring: Real-time performance metrics with color-coded indicators

📋 Advanced Log Management

• Smart Log Normalization: Automatic parsing and formatting of JSON, structured logs
• Powerful Search: Full-text search with literal matching (no regex) and result highlighting
• Advanced Filtering: Include/exclude patterns with complex boolean logic
• Time-based Filtering: Filter logs by date/time ranges with export capabilities
• Follow Mode: Real-time log streaming with auto-scroll
• Export Functionality: Save filtered logs to files

🎯 User Experience

• Mouse Support: Full mouse interaction for navigation, scrolling, and selection
• Responsive Design: Auto-adjusting columns with manual resize capability
• Persistent Configuration: Settings saved automatically between sessions
• Keyboard Shortcuts: Comprehensive hotkey support for power users
• Visual Indicators: Color-coded status, performance metrics, and alerts

Installation

PyPI Installation (Recommended)

pip install dtop

Alternative Installation Methods

From GitHub (Latest)

pip install git+https://github.com/StakeSquid/dtop.git

One-Line Install Script

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/StakeSquid/dtop/main/scripts/install.sh)"

Development Installation

# Clone repository
git clone https://github.com/StakeSquid/dtop
cd dtop

# Install in development mode
pip install -e .

# Or install dependencies manually
pip install docker
python -m dtop.main

Quick Start

After installation, simply run:

dtop

Make sure Docker is running and accessible to your user account.

Usage Guide

Main Interface Controls

Key	Action
↑/↓ or Mouse	Navigate containers
Enter or Click	Show container action menu
L	View container logs
I	Inspect container details
Q	Quit application
R	Refresh container list
/	Search/filter containers

Container Actions

When you select a container (Enter or Click), you can:

• 📋 Logs: View real-time and historical logs with advanced features
• 🔍 Inspect: View detailed container configuration and state
• ▶️ Start/Stop: Control container execution state
• ⏸️ Pause/Unpause: Temporarily suspend container processes
• 🔄 Restart: Restart the container
• 🔨 Recreate: Remove and recreate container from image
• 💻 Exec Shell: Open interactive shell session

Advanced Log Viewing

Search and Navigation

Key	Action
/	Search in logs (literal search only)
n/N	Next/previous search result
\	Advanced filter mode
↑/↓, PgUp/PgDn	Scroll through logs
Home/End	Jump to beginning/end

Log Controls

Key	Action
F	Toggle follow mode (real-time streaming)
N	Toggle log normalization
W	Toggle line wrapping
R	Time range filter
E	Export logs to file
ESC	Clear filters/return to main

Filter Syntax

The log viewer supports sophisticated filtering:

Basic Filters:

• error - Show lines containing "error"
• +error - Include lines with "error" (explicit include)
• -warning - Exclude lines with "warning"
• !debug - Exclude lines with "debug" (alternative syntax)

Advanced Filters:

error -debug                    # Lines with "error" but not "debug"
+error +warning -verbose       # Lines with "error" OR "warning", but not "verbose"  
"connection failed" -timeout   # Exact phrase matching with exclusion

Filter Features:

• Multiple inclusion filters work as OR logic
• Exclusion filters always take precedence
• Use quotes for multi-word phrases
• Press Tab to toggle case sensitivity
• Supports complex boolean combinations

Time-based Filtering

Press R in log view to filter by time range:

• Select start and end dates/times
• Export filtered results
• Combine with text filters
• Navigate through time ranges

Log Normalization

Press N to toggle automatic log normalization:

• Parses JSON logs into readable format
• Standardizes timestamp formats
• Extracts structured data fields
• Maintains original raw logs option

Configuration

dtop automatically saves your preferences to ~/.docker_tui.json:

{
  "columns": {
    "widths": [20, 15, 10, 8, 8, 12, 12, 15, 15],
    "visible": ["NAME", "IMAGE", "STATUS", "CPU%", "MEM%", "NET I/O", "DISK I/O", "CREATED AT", "UPTIME"]
  },
  "log_settings": {
    "normalize": true,
    "wrap_lines": false,
    "follow_mode": false
  },
  "ui_settings": {
    "mouse_enabled": true,
    "show_separators": true
  }
}

Customization Options

• Column Resize: Drag column separators with mouse
• Column Visibility: Configure which metrics to display
• Performance Tuning: Adjust refresh rates and collection intervals
• Color Themes: Customize status and performance indicators

Architecture

dtop is built with a modular architecture:

dtop/
├── core/           # Core TUI engine and stats collection
├── views/          # Log viewer and inspection interfaces  
├── actions/        # Container operation handlers
├── utils/          # Configuration, utilities, and log processing
└── scripts/        # Installation and maintenance scripts

Key Components

• Async Stats Collection: Parallel collection using aiohttp for performance
• Real-time Log Streaming: Efficient Docker API integration
• Responsive UI: Curses-based interface with mouse support
• Extensible Actions: Plugin-ready container operation system

Performance Features

• Parallel Processing: Concurrent stats collection for multiple containers
• Efficient Caching: Smart caching of container metadata and logs
• Memory Management: Automatic garbage collection and resource cleanup
• Optimized Rendering: Minimal screen updates and efficient drawing

Requirements

• Python: 3.8 or higher
• Docker: Docker daemon running and accessible
• Terminal: Mouse support and color capability recommended
• Dependencies: docker>=6.0.0 (automatically installed)

Optional Dependencies

• aiohttp>=3.8.0 - For enhanced async performance (install with pip install dtop[full])

Troubleshooting

Common Issues

Docker Connection Error:

# Ensure Docker is running
sudo systemctl start docker

# Check Docker socket permissions
sudo usermod -aG docker $USER
# Then logout and login again

Terminal Display Issues:

# Reset terminal if display is corrupted
reset

# Ensure terminal supports colors and mouse
echo $TERM

Performance Issues:

• Reduce number of containers being monitored
• Disable mouse support if experiencing lag
• Adjust refresh intervals in configuration

Getting Help

• GitHub Issues: Report bugs and feature requests
• Discussions: Community discussions and questions

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Clone the repository
git clone https://github.com/StakeSquid/dtop
cd dtop

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies
pip install -e .[dev]

# Run tests
python -m pytest tests/

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built with Python's curses library for terminal UI
• Uses the official Docker Python SDK
• Inspired by htop and similar system monitoring tools

---

⭐ Star this repository if dtop helps you manage Docker containers more efficiently!