diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e4b4564
--- /dev/null
+++ b/README.md
@@ -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**