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**
   ```bash
   git clone <repository-url>
   cd DokkuStatus
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Run the application**
   ```bash
   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**
   ```bash
   dokku apps:create status
   ```

2. **Set environment variables** (optional)
   ```bash
   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**
   ```bash
   git remote add dokku dokku@your-server:status
   git push dokku main
   ```

4. **Configure domain**
   ```bash
   dokku domains:add status status.peterstockings.com
   ```

5. **Enable SSL** (recommended)
   ```bash
   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:

```bash
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:

```bash
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:

```bash
# 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**