Fix security warnings

2025-10-20 21:52:32 +00:00
parent 9c584beddb
commit 10bcbf519c
7 changed files with 640 additions and 125 deletions
--- a/README.md
+++ b/README.md
@@ -1,73 +1,314 @@
-# Welcome to your Lovable project
+# 🐳 Docker WebUI

-## Project info
+A lightweight, self-hosted web interface for monitoring and controlling Docker containers in real-time.

-**URL**: https://lovable.dev/projects/ba519789-1c3e-4fe3-a965-cdc4a30e6a8b
+## ✨ Features

-## How can I edit this code?
+- **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

-There are several ways of editing your application.
+## 🚀 Quick Start

-**Use Lovable**
+### Prerequisites

-Simply visit the [Lovable Project](https://lovable.dev/projects/ba519789-1c3e-4fe3-a965-cdc4a30e6a8b) and start prompting.
+- Docker & Docker Compose
+- Host with Docker socket access (`/var/run/docker.sock`)

-Changes made via Lovable will be committed automatically to this repo.
+### Installation

-**Use your preferred IDE**
-
-If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable.
-
-The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating)
-
-Follow these steps:
-
-```sh
-# Step 1: Clone the repository using the project's Git URL.
-git clone <YOUR_GIT_URL>
-
-# Step 2: Navigate to the project directory.
-cd <YOUR_PROJECT_NAME>
-
-# Step 3: Install the necessary dependencies.
-npm i
-
-# Step 4: Start the development server with auto-reloading and an instant preview.
-npm run dev
+1. Clone this repository:
+```bash
+git clone <your-repo-url>
+cd docker-webui
 ```

-**Edit a file directly in GitHub**
+2. Copy and configure environment:
+```bash
+cp .env.example .env
+nano .env  # Edit admin credentials
+```

- Navigate to the desired file(s).
- Click the "Edit" button (pencil icon) at the top right of the file view.
- Make your changes and commit the changes.
+3. Set your admin credentials in `.env`:
+```env
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD=your-secure-password
+TZ=Europe/Copenhagen
+```

-**Use GitHub Codespaces**
+4. Build and start:
+```bash
+docker-compose up -d --build
+```

- Navigate to the main page of your repository.
- Click on the "Code" button (green button) near the top right.
- Select the "Codespaces" tab.
- Click on "New codespace" to launch a new Codespace environment.
- Edit files directly within the Codespace and commit and push your changes once you're done.
+5. Access the UI at `http://your-server-ip:8080`

-## What technologies are used for this project?
+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

-This project is built with:
+## 🔧 Configuration

- Vite
- TypeScript
- React
- shadcn-ui
- Tailwind CSS
+### Docker Compose

-## How can I deploy this project?
+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

-Simply open [Lovable](https://lovable.dev/projects/ba519789-1c3e-4fe3-a965-cdc4a30e6a8b) and click on Share -> Publish.
+### Environment Variables

-## Can I connect a custom domain to my Lovable project?
+| 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 |

-Yes, you can!
+### Changing the Port

-To connect a domain, navigate to Project > Settings > Domains and click Connect Domain.
+Edit `nginx.conf`:
+```nginx
+server {
+    listen 8082;  # Change from 8080 to your desired port
+    server_name _;
+    # ...
+}
+```

-Read more here: [Setting up a custom domain](https://docs.lovable.dev/features/custom-domain#custom-domain)
+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.