Docker Dashboard

A modern, responsive web dashboard for managing and monitoring Docker containers with SQLite database integration and manual customization capabilities.

Features

• Dynamic Container Tiles: Automatically discovers and displays all Docker containers
• SQLite Database: Persistent storage for custom tile configurations
• Manual Customization: Edit display names, icons, colors, descriptions, and URLs
• Real-time Monitoring: Live status updates and system metrics
• Responsive Design: Works on desktop, tablet, and mobile devices
• Portainer Integration: Optional enhanced functionality with Portainer API
• Container Management: Start, stop, and restart containers directly from the dashboard

Quick Start

Prerequisites

• Docker installed and running
• Python 3.7+
• Docker socket access (typically requires sudo)

Installation

1. Clone or download the project

2. Install dependencies:

   pip3 install -r requirements.txt
   

3. Configure environment:

   cp .env.example .env
   # Edit .env with your specific settings
   

4. Run the setup script (recommended):

   chmod +x setup.sh
   ./setup.sh
   

5. Or run manually:

   sudo python3 api.py
   

6. Access the dashboard: Open your browser to http://localhost:5000

Manual Setup

If you prefer to set up manually:

1. Install Python dependencies:

   pip3 install flask flask-cors docker requests python-dotenv
   

2. Initialize database:

   python3 -c "import database; db = database.DatabaseManager(); db.init_db()"
   

3. Start the application:

   sudo python3 api.py
   

Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	5000
HOST	Server host	0.0.0.0
DEBUG	Debug mode	False
REFRESH_INTERVAL	Auto-refresh interval (seconds)	30
PORTAINER_URL	Portainer URL (optional)	-
PORTAINER_USERNAME	Portainer username	-
PORTAINER_PASSWORD	Portainer password	-

Portainer Integration (Optional)

To use Portainer for enhanced container management:

1. Set up Portainer on your Docker host
2. Configure the environment variables:

   PORTAINER_URL=https://your-portainer-instance.com
   PORTAINER_USERNAME=your-username
   PORTAINER_PASSWORD=your-password
   

Usage

Dashboard Overview

• Server Information: CPU, memory, and disk usage
• Container Tiles: Visual representation of all Docker containers
• Live Status: Real-time container status (running/stopped)
• Uptime Display: Container uptime information
• Quick Actions: Open, edit, or manage containers

Customizing Tiles

1. Click the "Edit" button on any container tile
2. Modify the fields:
   • Display Name: Custom name shown on the tile
   • Icon: Font Awesome icon class (e.g., fas fa-cube)
   • Color: Tailwind CSS color (e.g., blue, green, red)
   • Description: Additional description text
   • URL: Custom URL for the application
3. Save changes - updates are immediately reflected

Syncing Containers

• Automatic: Containers sync every 30 seconds
• Manual: Click "Sync Apps" button to force refresh
• New containers: Automatically appear as new tiles
• Removed containers: Tiles are removed from display

API Endpoints

System Information

• GET /api/system - System metrics and uptime

Containers

• GET /api/containers - List all Docker containers
• GET /api/health/<container_name> - Check container health

Applications (Database)

• GET /api/applications - Get all applications from database
• GET /api/applications/<container_id> - Get specific application
• PUT /api/applications/<container_id> - Update application data
• DELETE /api/applications/<container_id> - Delete application
• POST /api/applications/sync - Sync with current containers

Portainer (Optional)

• GET /api/portainer/containers - Get containers via Portainer
• POST /api/portainer/container/<action>/<container_id> - Manage containers

Database Schema

The SQLite database (dashboard.db) contains the following table:

CREATE TABLE applications (
    container_id TEXT PRIMARY KEY,
    container_name TEXT NOT NULL,
    display_name TEXT,
    image TEXT,
    status TEXT,
    ports TEXT,
    uptime TEXT,
    icon TEXT DEFAULT 'fas fa-cube',
    color TEXT DEFAULT 'gray',
    description TEXT,
    url TEXT,
    custom_data TEXT
);

File Structure

├── api.py              # Main Flask API server
├── database.py         # SQLite database manager
├── template.html       # Frontend dashboard
├── portainer_integration.py  # Portainer API integration
├── setup.sh           # Setup and launch script
├── stop.sh            # Stop script (generated)
├── .env               # Environment variables (create from .env.example)
├── .env.example       # Environment template
├── requirements.txt   # Python dependencies
├── .gitignore         # Git ignore rules
├── dashboard.db       # SQLite database (created automatically)
└── logs/
    └── dashboard.log  # Application logs

Troubleshooting

Docker Permission Issues

If you see "Permission denied" errors:

# Add your user to docker group
sudo usermod -aG docker $USER
# Log out and back in

Port Issues

If port 5000 is already in use:

# Edit .env file and change PORT
PORT=5001

Database Issues

To reset the database:

rm dashboard.db
python3 -c "import database; db = database.DatabaseManager(); db.init_db()"

View Logs

tail -f logs/dashboard.log

Development

Adding New Features

1. Backend: Modify api.py for new endpoints
2. Database: Update database.py for schema changes
3. Frontend: Edit template.html for UI changes

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is open source and available under the MIT License.

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review the logs in logs/dashboard.log
3. Open an issue on the project repository