DokkuStatus/README.md

DokkuStatus 📊

A beautiful, real-time status dashboard for monitoring Dokku-deployed applications and infrastructure. Built with Flask and HTMX, featuring a modern glassmorphic UI with auto-refreshing metrics.

🌐 Live Demo: https://status.peterstockings.com/

Features

✨ Real-time Monitoring

• Auto-refreshing dashboard (configurable interval)
• Live CPU, RAM, and Docker disk usage gauges
• Container-level metrics for all Dokku apps
• Infrastructure monitoring (PostgreSQL, Redis, MySQL, MongoDB, MinIO, etc.)

🎨 Modern UI

• Glassmorphic design with gradient backgrounds
• Responsive grid layouts
• Smooth animations and hover effects
• Interactive donut charts for resource usage
• Status badges and visual indicators

📈 Comprehensive Metrics

• System information (host, CPU, RAM, Docker version)
• Per-app resource usage (CPU%, RAM, restart count)
• Docker disk usage breakdown
• Automatic warnings for high RAM usage or excessive restarts
• JSON API endpoint for programmatic access

Screenshots

The dashboard displays:

• Live Usage: Circular progress indicators for CPU, RAM, and Docker disk
• System: Host information, compute resources, and Docker stats
• Apps: Detailed table of all Dokku applications with links, status, and metrics
• Infra: Infrastructure containers (databases, caches, etc.)

Installation

Prerequisites

• Python 3.11+
• Docker (with permissions to run docker commands)
• Dokku deployment platform (optional, but recommended)

Local Development

1. Clone the repository

   git clone <repository-url>
   cd DokkuStatus
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Run the application

   python app.py
   

4. Access the dashboard Open http://localhost:5000 in your browser

Dokku Deployment

This application is designed to run on the same server as your Dokku apps:

1. Create the Dokku app

   dokku apps:create status
   

2. Set environment variables (optional)

   dokku config:set status POLL_SECONDS=10
   dokku config:set status APP_DOMAIN=peterstockings.com
   dokku config:set status SHOW_INFRA=1
   

3. Deploy via Git

   git remote add dokku dokku@your-server:status
   git push dokku main
   

4. Configure domain

   dokku domains:add status status.peterstockings.com
   

5. Enable SSL (recommended)

   dokku letsencrypt:enable status
   

Configuration

Configure the application using environment variables:

Variable	Default	Description
POLL_SECONDS	10	Auto-refresh interval in seconds
APP_DOMAIN	peterstockings.com	Base domain for inferring app URLs
DOCKER_BIN	/usr/bin/docker	Path to Docker binary
SHOW_INFRA	1	Show infrastructure containers (0=hide, 1=show)
APP_URL_OVERRIDES	{}	JSON map of app name to custom URL overrides

URL Overrides Example

If you have apps with custom domains that don't follow the <app>.<domain> pattern:

dokku config:set status APP_URL_OVERRIDES='{"gitea":"https://gitea.peterstockings.com","bp":"https://bloodpressure.example.com"}'

How It Works

Container Detection

The app automatically detects:

• Dokku Apps: Containers named <app>.web.1
• Infrastructure: Containers like dokku.postgres.*, dokku.redis.*, logspout, etc.

Metrics Collection

Uses Docker commands to gather:

• docker ps - Container list
• docker stats - Real-time resource usage
• docker info - Host system information
• docker system df - Disk usage breakdown
• docker inspect - Restart counts

Warning System

Automatically alerts when:

• App RAM usage ≥ 85%
• Container restarts ≥ 3

API Endpoint

Access raw JSON data programmatically:

curl https://status.peterstockings.com/api/status

Response includes:

• system - Host and Docker information
• gauges - Real-time metrics (CPU, RAM, disk)
• apps - Array of Dokku applications
• infra - Infrastructure containers
• warnings - Array of warning messages

Tech Stack

• Backend: Flask 2.2.2
• Frontend: HTML + HTMX (auto-refresh)
• Styling: Vanilla CSS with modern features
• Typography: Inter font (Google Fonts)
• Server: Gunicorn
• Deployment: Dokku (Heroku-compatible buildpack)

Project Structure

DokkuStatus/
├── app.py                 # Flask application & Docker integration
├── requirements.txt       # Python dependencies
├── Procfile              # Dokku/Heroku process definition
├── runtime.txt           # Python version specification
├── templates/
│   ├── index.html        # Main page with glassmorphic layout
│   └── apps_table.html   # Data display with donut charts & tables
└── README.md

Development

Adding New Metric Gauges

1. Update collect() in app.py to gather new metrics
2. Add the metric to the gauges dictionary
3. Update apps_table.html to display the new donut chart

Customizing the UI

• Colors: Modify the gradient values in index.html (default: #667eea to #764ba2)
• Donut charts: Edit the donut() macro in apps_table.html
• Refresh rate: Set POLL_SECONDS environment variable

Docker Permissions

The application requires Docker socket access. If running in a container, you may need to:

# Mount Docker socket (if containerized)
dokku docker-options:add status deploy "-v /var/run/docker.sock:/var/run/docker.sock"

⚠️ Security Note: This gives the container full Docker access. Only use on trusted servers.

License

MIT License - feel free to use and modify as needed.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

Support

For issues or questions, please open an issue on the repository.

---

Made with ❤️ for monitoring Dokku deployments