Deployment Guide

Prerequisites

• Docker Engine 24+ and Docker Compose v2
• TLS certificates for the domain (self-signed for testing)
• At least 4 GB RAM available for containers

Quick Start

# 1. Copy and configure environment
cp deployments/docker/.env.prod.example deployments/docker/.env.prod

# 2. Edit .env.prod — change ALL "CHANGE_ME_*" values
#    POSTGRES_PASSWORD, REDIS_PASSWORD, NATS_AUTH_TOKEN must be strong random strings

# 3. Place TLS certs
mkdir -p deployments/docker/nginx/certs
cp /path/to/tls.crt deployments/docker/nginx/certs/tls.crt
cp /path/to/tls.key deployments/docker/nginx/certs/tls.key

# 4. Build and start
make prod-up

# 5. Verify
make prod-logs
curl -k https://localhost/healthz

Architecture

                    ┌──────────┐
                    │  nginx   │ :80 (redirect) / :443 (TLS)
                    └────┬─────┘
                         │
              ┌──────────┼──────────┐
              │          │          │
         /api/*     /ws/*      /grpc/*
              │          │          │
              ▼          ▼          ▼
         ┌─────────────────────────────┐
         │       umoo backend       │ :8080 (HTTP) / :9090 (gRPC)
         └──────┬──────┬──────┬────────┘
                │      │      │
           ┌────┘      │      └────┐
           ▼           ▼           ▼
      ┌─────────┐ ┌─────────┐ ┌───────────────────┐
      │ postgres │ │  redis  │ │ nats cluster (3+1)│
      └─────────┘ └─────────┘ └───────────────────┘

Services

Service	Port	Purpose
nginx	80, 443	TLS termination, reverse proxy, rate limiting
umoo	8080, 9090	Backend HTTP API and gRPC bus
postgres	5432	Primary data store with RLS
redis	6379	Device registry, caching, rate limit counters
nats (×3 + seed)	4222	Cross-instance message routing

Environment Variables

See deployments/docker/.env.prod.example for the full list.

Critical variables that must be changed:

Variable	Description
POSTGRES_PASSWORD	PostgreSQL superuser password
REDIS_PASSWORD	Redis auth password
NATS_AUTH_TOKEN	NATS cluster auth token

TLS Certificates

Nginx expects certificates at:

deployments/docker/nginx/certs/tls.crt
deployments/docker/nginx/certs/tls.key

For self-signed testing:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout deployments/docker/nginx/certs/tls.key \
  -out deployments/docker/nginx/certs/tls.crt \
  -subj "/CN=umoo.local"

Scaling

The NATS cluster runs 3 nodes + 1 seed by default. To scale backend instances, run multiple umoo containers behind nginx. Each instance auto-discovers peers through NATS.

The docker-compose.prod.yml defines resource limits:

Service	Memory Limit
postgres	1 GB
redis	512 MB
nats (each)	256 MB

Database Migrations

Migrations run automatically on backend startup. The init script (init-db.sql) creates the initial database and enables required extensions.

Updating

git pull
make prod-down
make prod-up

Data volumes persist across restarts. To reset completely:

make prod-down
docker volume rm $(docker volume ls -q | grep umoo)
make prod-up