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

```bash
# 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):

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

2. **Enable auto-start**:

```bash
sudo systemctl enable control-center-kiosk
```

3. **Start the service**:

```bash
sudo systemctl start control-center-kiosk
```

4. **Check status and logs**:

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

### Manual Launch

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

### Uninstall

```bash
# 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`)

```bash
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)

```bash
VITE_API_URL=http://localhost:8080
```

### Docker Compose

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

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

## Development

### Local Development (non-Docker)

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

# Frontend
cd frontend
npm install
npm run dev
```

### Database Migrations

```bash
# 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

```bash
# 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

```bash
# Check network connectivity
docker compose exec frontend ping backend

# Verify backend is running
docker compose logs backend
```

### Kiosk browser won't start

```bash
# 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`:

```yaml
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 |