315 lines
9.1 KiB
Markdown
315 lines
9.1 KiB
Markdown
# 🐳 Docker WebUI
|
|
|
|
A lightweight, self-hosted web interface for monitoring and controlling Docker containers in real-time.
|
|
|
|
## ✨ Features
|
|
|
|
- **Real-time Monitoring** - Live metrics via WebSocket (CPU, memory, network, I/O)
|
|
- **Auto-discovery** - Containers created/removed via CLI appear instantly in UI
|
|
- **Container Control** - Start, stop, restart containers from the web interface
|
|
- **Live Logs** - Stream container logs in real-time with filtering
|
|
- **Discord Alerts** - Per-container notifications on stop/error
|
|
- **Dark Mode** - Beautiful, responsive interface
|
|
- **Single Admin** - Simple authentication with one admin user
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Docker & Docker Compose
|
|
- Host with Docker socket access (`/var/run/docker.sock`)
|
|
|
|
### Installation
|
|
|
|
1. Clone this repository:
|
|
```bash
|
|
git clone <your-repo-url>
|
|
cd docker-webui
|
|
```
|
|
|
|
2. Copy and configure environment:
|
|
```bash
|
|
cp .env.example .env
|
|
nano .env # Edit admin credentials
|
|
```
|
|
|
|
3. Set your admin credentials in `.env`:
|
|
```env
|
|
ADMIN_EMAIL=admin@example.com
|
|
ADMIN_PASSWORD=your-secure-password
|
|
TZ=Europe/Copenhagen
|
|
```
|
|
|
|
4. Build and start:
|
|
```bash
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
5. Access the UI at `http://your-server-ip:8080`
|
|
|
|
6. **First Login:**
|
|
- Navigate to `/settings` in your browser
|
|
- Click "Sign Up" to create the admin account
|
|
- Use the credentials from your `.env` file
|
|
- After creating the account, login with the same credentials
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Docker Compose
|
|
|
|
The service uses **host networking mode** for direct Docker socket access and requires:
|
|
- `/var/run/docker.sock` (read-only) - Docker API access
|
|
- `/proc` (read-only) - Host system metrics
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `ADMIN_EMAIL` | `admin@docker-webui.local` | Admin email address |
|
|
| `ADMIN_PASSWORD` | `changeme123` | Admin password (min 6 chars) |
|
|
| `TZ` | `Europe/Copenhagen` | Server timezone |
|
|
|
|
### Changing the Port
|
|
|
|
Edit `nginx.conf`:
|
|
```nginx
|
|
server {
|
|
listen 8082; # Change from 8080 to your desired port
|
|
server_name _;
|
|
# ...
|
|
}
|
|
```
|
|
|
|
Then rebuild:
|
|
```bash
|
|
docker-compose down
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
## 📊 Usage
|
|
|
|
### Dashboard
|
|
- **Host Metrics** - CPU, RAM, network, uptime
|
|
- **Container List** - All containers with live stats
|
|
- **Quick Actions** - Start/stop/restart buttons
|
|
- **Auto-refresh** - Updates every 2-5 seconds
|
|
|
|
### Container Details
|
|
- Real-time metrics graphs
|
|
- Live log streaming (no storage, ephemeral)
|
|
- Container configuration details
|
|
- Per-container alert settings
|
|
|
|
### Settings
|
|
- Discord webhook configuration
|
|
- Metrics refresh interval
|
|
- Alert debounce settings
|
|
- Error pattern regex
|
|
|
|
## 🔔 Discord Alerts
|
|
|
|
Set up per-container Discord notifications:
|
|
|
|
1. Create a Discord webhook in your server
|
|
2. In WebUI Settings, add your webhook URL
|
|
3. Enable alerts for specific containers
|
|
4. Configure triggers:
|
|
- **Container Stopped** - Alert when container stops/crashes
|
|
- **Error Pattern** - Match regex in logs (default: `(?i)(error|err|exception|traceback|crit(ical)?)`)
|
|
|
|
Example alert:
|
|
```json
|
|
{
|
|
"username": "Docker WebUI",
|
|
"embeds": [{
|
|
"title": "Container Stopped",
|
|
"color": 15158332,
|
|
"fields": [
|
|
{"name": "Container", "value": "redis:prod"},
|
|
{"name": "Reason", "value": "stop event"},
|
|
{"name": "Time", "value": "2025-10-20T10:22:31Z"}
|
|
]
|
|
}]
|
|
}
|
|
```
|
|
|
|
## 🔒 Security
|
|
|
|
⚠️ **Important Security Considerations:**
|
|
|
|
- **Root Required** - Container needs root access to Docker socket
|
|
- **Trusted Hosts Only** - Docker socket access = full system control
|
|
- **Single Admin** - Only one user (configured via env vars)
|
|
- **Read-only Mounts** - Socket and `/proc` are mounted read-only
|
|
- **No Public Exposure** - Always use behind HTTPS reverse proxy
|
|
- **Audit Logging** - All control actions logged to database
|
|
|
|
### Reverse Proxy Setup (Recommended)
|
|
|
|
Example Nginx configuration:
|
|
```nginx
|
|
server {
|
|
listen 443 ssl http2;
|
|
server_name docker.example.com;
|
|
|
|
ssl_certificate /path/to/cert.pem;
|
|
ssl_certificate_key /path/to/key.pem;
|
|
|
|
location / {
|
|
proxy_pass http://localhost:8080;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Upgrade $http_upgrade;
|
|
proxy_set_header Connection "upgrade";
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
}
|
|
}
|
|
```
|
|
|
|
## 🛠️ Development
|
|
|
|
### Tech Stack
|
|
|
|
- **Frontend**: React 18 + TypeScript + Vite
|
|
- **Backend**: Lovable Cloud (Supabase)
|
|
- **UI Framework**: shadcn/ui + Tailwind CSS
|
|
- **Real-time**: WebSocket for metrics streaming
|
|
- **Deployment**: Docker + Nginx
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start dev server
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
docker-webui/
|
|
├── src/
|
|
│ ├── pages/ # Dashboard, Login, Settings
|
|
│ ├── components/ # Reusable UI components
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ └── integrations/ # Supabase client
|
|
├── supabase/
|
|
│ ├── functions/ # Edge functions (Docker API)
|
|
│ └── config.toml # Function configuration
|
|
├── Dockerfile # Multi-stage build
|
|
├── nginx.conf # Web server config
|
|
└── docker-compose.yml # Service definition
|
|
```
|
|
|
|
## 📝 Architecture
|
|
|
|
```
|
|
┌──────────────┐ WebSocket ┌───────────────┐
|
|
│ Browser │◄────────────────────────►│ docker-metrics│
|
|
│ (React) │ │ Edge Function │
|
|
└──────────────┘ └───────┬───────┘
|
|
│
|
|
┌──────────────┐ REST API ┌───────▼───────┐
|
|
│ Dashboard │◄────────────────────────►│ docker-api │
|
|
│ Frontend │ │ Edge Function │
|
|
└──────────────┘ └───────┬───────┘
|
|
│
|
|
┌──────▼─────────┐
|
|
│ /var/run/ │
|
|
│ docker.sock │
|
|
└────────────────┘
|
|
```
|
|
|
|
**Flow:**
|
|
1. Frontend connects via WebSocket for real-time metrics
|
|
2. Backend edge functions read Docker socket via Unix socket
|
|
3. Container stats streamed every 2 seconds
|
|
4. Container list auto-updates via polling + WebSocket
|
|
|
|
## 🚀 Features in Detail
|
|
|
|
### Auto-Discovery
|
|
- Detects new containers within 5 seconds
|
|
- Automatically removes deleted containers from UI
|
|
- No manual refresh needed
|
|
- Works with `docker run`, `docker-compose`, etc.
|
|
|
|
### Live Metrics
|
|
- **Host**: CPU %, RAM usage, network I/O, uptime
|
|
- **Containers**: CPU %, memory, network RX/TX, block I/O
|
|
- **Refresh**: 2-second intervals via WebSocket
|
|
- **No Storage**: All metrics are ephemeral (not saved)
|
|
|
|
### Log Streaming
|
|
- Streams directly from Docker (no disk storage)
|
|
- Client-side regex filtering
|
|
- Color-coded timestamps
|
|
- Auto-scroll with pause/resume
|
|
- Logs disappear on browser close
|
|
|
|
## 🔮 Roadmap
|
|
|
|
- [ ] Multi-host support (lightweight agent model)
|
|
- [ ] Historical metrics with charts
|
|
- [ ] Advanced health check rules
|
|
- [ ] Multi-language UI (English/Danish)
|
|
- [ ] Docker Compose stack management
|
|
- [ ] Volume and network management
|
|
- [ ] Resource limits configuration
|
|
|
|
## ⚠️ Limitations
|
|
|
|
- **No Shell Access** - WebUI does not provide terminal/exec access
|
|
- **No Log Storage** - Logs stream live but are not persisted
|
|
- **Single Host** - Multi-host requires future agent architecture
|
|
- **Rate Limits** - Discord webhooks have rate limits (use debounce)
|
|
- **Root Access** - Requires privileged Docker socket access
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Container not accessible from browser
|
|
- Check that you're using host networking mode
|
|
- Verify firewall allows port 8080
|
|
- Try accessing via `http://HOST_IP:8080`
|
|
|
|
### Metrics not updating
|
|
- Check WebSocket connection (WiFi icon in header)
|
|
- Verify `/var/run/docker.sock` is mounted
|
|
- Check edge function logs in Lovable Cloud
|
|
|
|
### Can't login
|
|
- Ensure you created the admin account first (Settings → Sign Up)
|
|
- Verify credentials match `.env` file
|
|
- Check browser console for errors
|
|
|
|
## 📄 License
|
|
|
|
MIT License
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions welcome! Please:
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Commit your changes
|
|
4. Open a Pull Request
|
|
|
|
## 💬 Support
|
|
|
|
- **Issues**: Report bugs via GitHub Issues
|
|
- **Discussions**: Ask questions in GitHub Discussions
|
|
- **Documentation**: See inline code comments
|
|
|
|
---
|
|
|
|
**Built with ❤️ using [Lovable](https://lovable.dev)**
|
|
|
|
Deploy on trusted infrastructure only. Docker socket access = full system control.
|