Add readme
This commit is contained in:
Peter Stockings
221
README.md
Normal file
221
README.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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**
|
||||
Reference in New Issue
Block a user