Control-Center/README-deployment.md

Control Center Deployment Guide

This document covers the Docker Compose deployment and kiosk configuration for the Control Center Go + React application.

Quick Start

# Start all services (backend, frontend, database)
docker compose up -d

# View logs
docker compose logs -f

# Stop all services
docker compose down

# Stop and remove volumes (database data)
docker compose down -v

Architecture

┌─────────────────┐
│   Frontend      │  Port 3000 (host) → 80 (container)
│   React + nginx │  Serves SPA, proxies /api/ to backend
└────────┬────────┘
         │
         │ HTTP
         │
┌────────▼────────┐
│   Backend       │  Port 8080 (host) → 8080 (container)
│   Go HTTP API   │  PostgreSQL-backed REST API
└────────┬────────┘
         │
         │ PostgreSQL
         │
┌────────▼────────┐
│   PostgreSQL    │  Port 5432 (internal only)
│   Database      │  Persistent volume at /var/lib/postgresql/data
└─────────────────┘

Services

Backend (go-backend)

• Image: Custom alpine:latest with Go binary
• Port: 8080
• Build: Multi-stage from go-backend/Dockerfile
• Environment Variables:
  • PORT (default: 8080)
  • DATABASE_URL (PostgreSQL DSN)
  • CORS_ORIGIN (default: *)
  • LOG_LEVEL (default: info)
  • ENVIRONMENT (default: development)
  • GATEWAY_URL (OpenClaw gateway endpoint)

Frontend (frontend)

• Image: nginx:1.27-alpine
• Port: 80 (internal) → 3000 (host)
• Build: Multi-stage from frontend/Dockerfile
  • Node 22 for build
  • Nginx 1.27 for serving
• Config: Custom nginx config in frontend/nginx.conf
• Environment Variables:
  • VITE_API_URL (passed at build time via Vite config)

Database (db)

• Image: postgres:16-alpine
• Port: 5432 (internal only)
• Volume: postgres-data:/var/lib/postgresql/data
• Environment Variables:
  • POSTGRES_USER (default: controlcenter)
  • POSTGRES_PASSWORD (default: controlcenter)
  • POSTGRES_DB (default: controlcenter)

Kiosk Mode

For dedicated display installations (e.g., control center dashboard), Chromium can run in kiosk mode.

Installation

1. Install the systemd service (on Debian/Ubuntu with systemd):

sudo cp kiosk/control-center-kiosk.service /etc/systemd/system/
sudo systemctl daemon-reload

2. Enable auto-start:

sudo systemctl enable control-center-kiosk

3. Start the service:

sudo systemctl start control-center-kiosk

4. Check status and logs:

sudo systemctl status control-center-kiosk
sudo journalctl -u control-center-kiosk -f

Manual Launch

# From project root
./kiosk/start-kiosk.sh http://localhost:3000

Uninstall

# Stop and disable service
sudo systemctl stop control-center-kiosk
sudo systemctl disable control-center-kiosk
sudo rm /etc/systemd/system/control-center-kiosk.service
sudo systemctl daemon-reload

Kiosk Requirements

• Browser: chromium-browser (install via apt-get install chromium)
• Display: X11 session with DISPLAY=:0
• User: Must run as a user with X11 access (typically overseer)
• Permissions: Read access to the project directory

Environment Variables Reference

Backend (go-backend/.env)

PORT=8080
DATABASE_URL=postgresql://controlcenter:controlcenter@localhost:5432/controlcenter?sslmode=disable
CORS_ORIGIN=*
LOG_LEVEL=info
ENVIRONMENT=development
GATEWAY_URL=http://localhost:18789/api/agents
GATEWAY_POLL_INTERVAL=5s

Frontend (build-time)

VITE_API_URL=http://localhost:8080

Docker Compose

Set via services.<name>.environment in docker-compose.yml:

services:
  backend:
    environment:
      - DATABASE_URL=...
  frontend:
    environment:
      - VITE_API_URL=...
  db:
    environment:
      - POSTGRES_USER=...
      - POSTGRES_PASSWORD=...
      - POSTGRES_DB=...

Development

Local Development (non-Docker)

# Backend
cd go-backend
go run ./cmd/server/main.go

# Frontend
cd frontend
npm install
npm run dev

Database Migrations

# If using pgx/migrate or similar
# The database is created automatically on first connection if it doesn't exist

Troubleshooting

Backend won't connect to database

# Check database container status
docker compose ps

# View database logs
docker compose logs db

# Test database connectivity from backend
docker compose exec backend ping db

Frontend can't reach backend

# Check network connectivity
docker compose exec frontend ping backend

# Verify backend is running
docker compose logs backend

Kiosk browser won't start

# Check Chromium installation
which chromium-browser

# Check X11 forwarding
echo $DISPLAY

# Manual launch for debugging
./kiosk/start-kiosk.sh http://localhost:3000

Port conflicts

If ports 8080, 3000, or 5432 are already in use, modify docker-compose.yml:

services:
  backend:
    ports:
      - "8081:8080"  # Change host port
  frontend:
    ports:
      - "3001:80"    # Change host port

Production Considerations

1. HTTPS: Add a reverse proxy (nginx/Traefik) for SSL termination
2. Database security: Use strong passwords, enable SSL
3. CORS: Restrict CORS_ORIGIN to production domain
4. Logs: Configure log aggregation (e.g., ELK, Loki)
5. Backups: Regular PostgreSQL volume backups
6. Monitoring: Add health checks and alerting

Files

File/Directory	Purpose
docker-compose.yml	Service definitions and configuration
.env.example	Environment variable template
go-backend/Dockerfile	Backend build definition
frontend/Dockerfile	Frontend build definition
frontend/nginx.conf	Nginx config for SPA routing
kiosk/start-kiosk.sh	Kiosk browser startup script
kiosk/control-center-kiosk.service	Systemd unit for auto-start