🐳 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:

git clone <your-repo-url>
cd docker-webui

2. Copy and configure environment:

cp .env.example .env
nano .env  # Edit admin credentials

3. Set your admin credentials in .env:

ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your-secure-password
TZ=Europe/Copenhagen

4. Build and start:

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:

server {
    listen 8082;  # Change from 8080 to your desired port
    server_name _;
    # ...
}

Then rebuild:

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:

{
  "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:

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

# 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

Deploy on trusted infrastructure only. Docker socket access = full system control.