docker-watch-desk/PROJECT_DOCUMENTATION.md

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:

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:

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:

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

// 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