ClawUI Deployment Guide

Target: UAT / Local deployment on Mac Mini Stack: Go backend · SolidStart frontend · Redis Transport: Docker Compose (Docker for Mac / Podman Desktop)

Architecture

┌──────────────────────────────────┐
│  Browser                         │
└────────────┬─────────────────────┘
             │ HTTP  :3000
┌────────────▼─────────────────────┐
│  Frontend  (SolidStart)          │
│  Port 3000                       │
│  Proxies /api → backend          │
└────────────┬─────────────────────┘
             │ HTTP  :8080 (internal)
┌────────────▼─────────────────────┐
│  Backend   (Go / Echo)           │
│  Port 8080                       │
│  SSE, REST API, Queue service    │
└────────────┬─────────────────────┘
             │ TCP   :6379 (internal)
┌────────────▼─────────────────────┐
│  redis     (Redis 7 Alpine)      │
│  Port 6379                       │
│  Persistent AOF storage          │
└──────────────────────────────────┘

All three containers run on a private clawui bridge network. Only ports 3000, 8080, and 6379 are exposed on the host.

Prerequisites

Tool	Version	Notes
Docker	≥ 24	Docker for Mac or OrbStack
Docker Compose	v2	`docker compose` (not `docker-compose`)
Node.js	≥ 22	Only needed for local dev, not Docker
Go	≥ 1.24	Only needed for local dev, not Docker

Quick Start

1. Configure environment

cd devops/
cp .env.example .env
# Edit .env — at minimum set OPENCLAW_TOKEN

Key variables:

Variable	Default	Description
`OPENCLAW_ENDPOINT`	`http://localhost:8000`	OpenClaw gateway URL
`OPENCLAW_TOKEN`	(required)	Auth token for OpenClaw
`CORS_ALLOWED_ORIGINS`	`http://localhost:3000`	Restrict CORS
`FRONTEND_PORT`	`3000`	Host port for frontend
`REDIS_PORT`	`6379`	Host port for Redis

2. Deploy

./scripts/deploy.sh up

This will:

Build the Go binary (multi-stage Docker build)
Build the SolidStart frontend (node:22-alpine)
Start Redis, wait for it to be healthy
Start the backend, wait for /health to return 200
Start the frontend

3. Verify

./scripts/deploy.sh health

Expected output:

[OK]    Redis
[OK]    Backend health (http://localhost:8080/health)
[OK]    Frontend (http://localhost:3000/)

Open your browser at http://localhost:3000

Startup Sequence

Services start in this strict order (Docker depends_on + condition: service_healthy):

redis           → waits until redis-cli ping = PONG
clawui-backend  → waits until GET /health = 200
clawui-frontend → waits until HTTP 200 on :3000

The backend will not start until Redis is healthy. The frontend will not start until the backend is healthy. This prevents the frontend from serving a broken UI on first load.

Health Check Endpoints

Service	Endpoint	Method	Expected
Backend	`http://localhost:8080/health`	GET	`200 OK`
Redis	`redis-cli ping` (internal)	—	`PONG`
Frontend	`http://localhost:3000/`	GET	`200 OK`

Common Commands

# Start everything
./scripts/deploy.sh up

# Stop everything
./scripts/deploy.sh down

# Restart everything
./scripts/deploy.sh restart

# View all logs (Ctrl-C to exit)
./scripts/deploy.sh logs

# View backend logs only
./scripts/deploy.sh logs clawui-backend

# Check container health
./scripts/deploy.sh status

# Verify HTTP endpoints
./scripts/deploy.sh health

Updating the Application

# Pull latest code, rebuild and restart
git pull
./scripts/deploy.sh restart

Images are rebuilt from source on every up call. Docker layer cache makes rebuilds fast for unchanged layers.

Data Persistence

Redis data is stored in a named Docker volume redis_data. It persists across container restarts and docker compose down. To wipe all data:

docker compose down -v   # removes volumes too

Local Development (without Docker)

For active development, run services individually: Redis (if not using system Redis):

docker run -d -p 6379:6379 redis:7-alpine

Backend:

cd backend/go/clawui
cp .env.example .env   # fill in values
go run ./cmd/server

Frontend:

cd admin/apps/clawui
npm install
npm run dev   # runs on :3001 in dev mode

Note: Dev mode runs on port 3001. The app.config.ts proxies /api to http://localhost:8080 automatically.

Troubleshooting

Backend won’t start — “redis: connection refused”

Redis isn’t healthy yet. Wait 10–15 seconds, or check:

docker logs clawui-redis

Frontend build fails — “Cannot find module”

Node dependencies may be stale. The Docker build handles this, but for local dev:

cd admin/apps/clawui && npm install

Backend returns 500 — “openclaw: connection refused”

OPENCLAW_ENDPOINT is unreachable. Verify the gateway is running and the endpoint URL in .env is correct.

CORS errors in browser

Ensure CORS_ALLOWED_ORIGINS in .env matches the origin your browser uses (e.g., http://localhost:3000).

Port conflict

If port 3000, 8080, or 6379 is in use:

lsof -i :3000

Override ports in .env:

FRONTEND_PORT=3001
REDIS_PORT=6380

Known Issues

ID	Severity	Description
BUG-001	Critical	OpenClaw adapter is mock-only; no real AI integration
SEC-001	Critical	CORS wildcard — set `CORS_ALLOWED_ORIGINS` in .env
SEC-002	Critical	SSE endpoints have no auth middleware
BUG-011	Critical	Frontend does not send idempotency keys on retry
BUG-006	High	No SSE reconnection on stream failure

UAT note: The deployment is functional for testing the UI, content rendering, pinning, and session persistence. Real AI responses require OPENCLAW_TOKEN to point to a working gateway.

Documentations

Getting Started

API

Modules

Infrastructure

Development

Guides

ClawUI Deployment Guide

Architecture

Prerequisites

Quick Start

1. Configure environment

2. Deploy

3. Verify

Startup Sequence

Health Check Endpoints

Common Commands

Updating the Application

Data Persistence

Local Development (without Docker)

Troubleshooting

Backend won’t start — “redis: connection refused”

Frontend build fails — “Cannot find module”

Backend returns 500 — “openclaw: connection refused”

CORS errors in browser

Port conflict

Known Issues

​Architecture

​Prerequisites

​Quick Start

​1. Configure environment

​2. Deploy

​3. Verify

​Startup Sequence

​Health Check Endpoints

​Common Commands

​Updating the Application

​Data Persistence

​Local Development (without Docker)

​Troubleshooting

​Backend won’t start — “redis: connection refused”

​Frontend build fails — “Cannot find module”

​Backend returns 500 — “openclaw: connection refused”

​CORS errors in browser

​Port conflict

​Known Issues

Architecture

Prerequisites

Quick Start

1. Configure environment

2. Deploy

3. Verify

Startup Sequence

Health Check Endpoints

Common Commands

Updating the Application

Data Persistence

Local Development (without Docker)

Troubleshooting

Backend won’t start — “redis: connection refused”

Frontend build fails — “Cannot find module”

Backend returns 500 — “openclaw: connection refused”

CORS errors in browser

Port conflict

Known Issues