Add project description
This commit is contained in:
gpt-engineer-app[bot]
359
PROJECT_DOCUMENTATION.md
Normal file
359
PROJECT_DOCUMENTATION.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user