From 6c5b44844ba6139584f1ca4484f545671cd4f12a Mon Sep 17 00:00:00 2001 From: "gpt-engineer-app[bot]" <159125892+gpt-engineer-app[bot]@users.noreply.github.com> Date: Mon, 20 Oct 2025 23:14:18 +0000 Subject: [PATCH] Add project description --- PROJECT_DOCUMENTATION.md | 359 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 PROJECT_DOCUMENTATION.md diff --git a/PROJECT_DOCUMENTATION.md b/PROJECT_DOCUMENTATION.md new file mode 100644 index 0000000..dc1cd85 --- /dev/null +++ b/PROJECT_DOCUMENTATION.md @@ -0,0 +1,359 @@ +# Docker WebUI - Complete Project Documentation + +## Project Overview + +Docker WebUI is a web-based management interface for Docker containers. It provides a clean, modern UI for monitoring and controlling Docker containers on a host system, with authentication, real-time metrics, and audit logging. + +## Technology Stack + +### Frontend +- **React 18.3.1** - UI framework +- **TypeScript** - Type safety +- **Vite** - Build tool and dev server +- **Tailwind CSS** - Styling +- **shadcn/ui** - Component library +- **TanStack Query** - Data fetching and caching +- **React Router** - Routing + +### Backend +- **Lovable Cloud (Supabase)** - Backend infrastructure + - Authentication + - Database (PostgreSQL) + - Edge Functions (Deno) + - Real-time subscriptions + +### Infrastructure +- **Docker** - Containerization +- **Nginx** - Production web server +- **Unix Socket** - Direct Docker API access + +## Core Features + +### 1. Authentication System +- Single admin user model +- Email/password authentication via Supabase Auth +- Auto-confirm email signups (for development) +- Protected routes with session management +- JWT token-based API authorization + +### 2. Dashboard +- Lists all Docker containers (running and stopped) +- Container status indicators +- Quick actions: Start, Stop, Restart +- Auto-refresh every 5 seconds +- Loading states and error handling + +### 3. Real-time Metrics +- WebSocket connection for live data +- Host metrics: + - CPU usage + - Memory (total, free, available, used) + - System uptime +- Per-container metrics: + - CPU percentage + - Memory usage/limit + - Network I/O (RX/TX) + - Block I/O (read/write) +- Automatic reconnection on disconnect + +### 4. Container Management +- View detailed container information +- Control container lifecycle (start/stop/restart) +- View container logs +- Monitor container-specific metrics +- Audit trail for all actions + +### 5. Settings Page +- User profile management +- Global settings configuration +- Admin account management + +## Architecture + +### Frontend Structure + +``` +src/ +├── components/ +│ ├── ui/ # shadcn/ui components +│ └── ProtectedRoute.tsx # Auth wrapper +├── hooks/ +│ ├── useDockerContainers.ts # Container data fetching +│ └── useDockerMetrics.ts # Real-time metrics WebSocket +├── integrations/ +│ └── supabase/ # Auto-generated Supabase client +├── pages/ +│ ├── Login.tsx # Authentication page +│ ├── Dashboard.tsx # Main container list +│ ├── ContainerDetails.tsx # Single container view +│ ├── Settings.tsx # Settings page +│ └── NotFound.tsx # 404 page +└── App.tsx # Root component with routing +``` + +### Backend Structure + +``` +supabase/ +├── functions/ +│ ├── docker-api/ # Main Docker operations +│ ├── docker-logs/ # Container log streaming +│ └── docker-metrics/ # Real-time metrics WebSocket +└── migrations/ # Database schema migrations +``` + +## Database Schema + +### Tables + +#### `global_settings` +- `id` (UUID, Primary Key) +- `user_id` (UUID, references auth.users) +- `created_at` (Timestamp) +- `updated_at` (Timestamp) +- Stores global application settings + +#### `audit_logs` +- `id` (UUID, Primary Key) +- `user_id` (UUID, references auth.users) +- `action` (Text) - start/stop/restart +- `container_id` (Text) +- `container_name` (Text) +- `details` (JSONB) +- `created_at` (Timestamp) +- Tracks all container actions for auditing + +### Row Level Security (RLS) +- All tables have RLS enabled +- Users can only access their own data +- Policies enforce user_id checks + +## API Endpoints + +### Docker API Edge Function +**Base URL**: `/functions/v1/docker-api` + +#### GET `/containers` +Lists all Docker containers +- Returns: Array of container objects + +#### GET `/containers/:id` +Get specific container details +- Returns: Detailed container object + +#### POST `/containers/:id/start` +Start a container +- Creates audit log entry + +#### POST `/containers/:id/stop` +Stop a container +- Creates audit log entry + +#### POST `/containers/:id/restart` +Restart a container +- Creates audit log entry + +### Docker Logs Edge Function +**Endpoint**: `/functions/v1/docker-logs` + +WebSocket connection for streaming container logs +- Query params: `container_id` + +### Docker Metrics Edge Function +**Endpoint**: `/functions/v1/docker-metrics` + +WebSocket connection for real-time metrics +- Streams host and container metrics every 2 seconds + +## Docker Integration + +### Unix Socket Access +The application accesses Docker via Unix socket at `/var/run/docker.sock` + +**docker-compose.yml configuration**: +```yaml +volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro +``` + +### Container Deployment + +#### Build Arguments +- `VITE_SUPABASE_URL` +- `VITE_SUPABASE_PUBLISHABLE_KEY` +- `VITE_SUPABASE_PROJECT_ID` + +#### Runtime Environment +- `TZ` - Timezone +- `ADMIN_EMAIL` - Admin account email +- `ADMIN_PASSWORD` - Admin account password + +#### Volumes +- `/var/run/docker.sock:/var/run/docker.sock:ro` - Docker API access +- `/proc:/host/proc:ro` - Host metrics access + +## Security Considerations + +### Authentication +1. All API endpoints require authentication +2. JWT tokens validated on every request +3. User session persisted in localStorage +4. Protected routes redirect to login if unauthenticated + +### Docker Access +1. Docker socket mounted read-only (`:ro`) +2. All container actions logged to audit_logs +3. User authentication required for all operations + +### Database +1. RLS policies enforce data isolation +2. No direct database access from frontend +3. All queries go through authenticated edge functions + +### Environment Variables +1. Sensitive keys in Supabase Secrets (never in code) +2. Build-time variables for Vite +3. Runtime variables for container configuration + +## Deployment + +### Environment Setup + +1. **Create `.env` file**: +```env +VITE_SUPABASE_URL=your_supabase_url +VITE_SUPABASE_PUBLISHABLE_KEY=your_publishable_key +VITE_SUPABASE_PROJECT_ID=your_project_id +PORT=8080 +ADMIN_EMAIL=admin@example.com +ADMIN_PASSWORD=secure_password +TZ=Europe/Copenhagen +``` + +2. **Build and run**: +```bash +docker-compose up -d --build +``` + +3. **Access**: `http://localhost:8080` + +4. **First-time setup**: + - Click "Create admin account" + - Enter credentials from `.env` + - Sign in with created account + +## Current Issues + +### Unauthorized Error +The application currently returns "Unauthorized" errors because: +1. Edge functions need Docker socket access +2. Edge functions run in Supabase cloud, not on the Docker host +3. Cannot access `/var/run/docker.sock` from cloud functions + +### Solution Architecture Needed + +To make this work, you need one of these approaches: + +#### Option 1: Self-hosted Backend +- Deploy Supabase locally on the Docker host +- Or create custom backend API running on the host +- Backend has direct socket access + +#### Option 2: Agent Architecture +- Install an agent on the Docker host +- Agent exposes REST/WebSocket API +- Frontend connects to agent instead of cloud functions +- Agent handles Docker socket communication + +#### Option 3: Direct Access (Development Only) +- Frontend makes requests directly to Docker API +- Requires CORS and authentication setup +- Not recommended for production + +## Rebuilding This Project + +### Using Traditional Stack + +**Backend**: Node.js/Express +```javascript +// Server running on Docker host +const express = require('express'); +const Docker = require('dockerode'); +const docker = new Docker({ socketPath: '/var/run/docker.sock' }); + +app.get('/api/containers', async (req, res) => { + const containers = await docker.listContainers({ all: true }); + res.json(containers); +}); +``` + +**Frontend**: Same React app, but connect to local backend + +### Using Alternative Platforms + +1. **Portainer** - Full-featured Docker management (already exists) +2. **Yacht** - Lightweight Docker dashboard +3. **Dockge** - Stack-oriented Docker compose manager +4. **Custom PHP/Python** - Traditional LAMP/LEMP stack with Docker SDK + +## File Structure Reference + +``` +project/ +├── .env # Environment configuration +├── .env.example # Environment template +├── docker-compose.yml # Docker orchestration +├── Dockerfile # Multi-stage build +├── nginx.conf # Nginx configuration +├── package.json # Dependencies +├── tailwind.config.ts # Tailwind configuration +├── vite.config.ts # Vite configuration +├── src/ +│ ├── App.tsx # Root component +│ ├── main.tsx # Entry point +│ ├── index.css # Global styles +│ ├── components/ # React components +│ ├── pages/ # Page components +│ ├── hooks/ # Custom hooks +│ ├── lib/ # Utilities +│ └── integrations/ # Third-party integrations +├── supabase/ +│ ├── config.toml # Supabase configuration +│ ├── functions/ # Edge functions +│ └── migrations/ # Database migrations +└── public/ # Static assets +``` + +## Key Lessons + +1. **Cloud functions can't access local Unix sockets** - Need agent on host +2. **WebSocket for real-time data** - Better UX than polling +3. **Multi-stage Docker builds** - Smaller production images +4. **RLS for security** - Database-level access control +5. **shadcn/ui for rapid development** - Pre-built accessible components + +## Next Steps for Functional Implementation + +1. **Create a local agent**: + - Go/Rust/Node.js service on Docker host + - REST API for container operations + - WebSocket for metrics + - Authentication via JWT + +2. **Update frontend**: + - Connect to agent instead of cloud functions + - Keep same UI/UX + - Add agent health monitoring + +3. **Deployment**: + - Agent runs on Docker host + - Frontend can be anywhere (cloud/host) + - Secure communication with TLS + +## License & Credits + +Built with: +- Lovable.dev - AI-powered development platform +- Supabase - Backend infrastructure +- shadcn/ui - Component library +- Tailwind CSS - Utility-first CSS framework