Deployment

The web client is optional, but when enabled it typically sits behind a proxy that serves static assets and forwards API/WebSocket traffic to the embedded web host in moor or to moor-web-host in split deployments.

Typical Topology

Browser → nginx (or other proxy) → moor web host → daemon runtime
            ↓
      Static assets
      (HTML/CSS/JS)

1. Browser loads static web client assets (HTML/CSS/JS) from the proxy
2. The proxy forwards /v1/, /auth/, /ws/, and /webhooks/ traffic to the web host
3. The web host relays RPC and event traffic to the daemon runtime

Deployment Options

Docker Compose (Recommended)

The simplest way to deploy is using the provided Docker Compose configurations:

# Single-process web deployment
docker compose -f deploy/single-process/web/docker-compose.yml up -d

# Clustered HTTPS with Let's Encrypt
docker compose -f deploy/clustered/web-ssl/docker-compose.yml up -d

Debian Packages

The published 1.0.2 Debian channel does not include a matching Meadow package. For a Debian/Ubuntu web deployment, build the server and web client packages from the same monorepo checkout, then configure a reverse proxy such as nginx:

# From the mooR repository root
./deploy/debian-packages/build-all-packages.sh

# Install the combined server and web client
sudo dpkg -i target/debian/moor_*.deb target/debian/moor-web-client_*.deb

# Or install the split web host:
sudo dpkg -i target/debian/moor-daemon_*.deb target/debian/moor-web-host_*.deb \
    target/debian/moor-web-client_*.deb

Web client files are installed to /usr/share/moor/web-client/. Adapt the nginx configuration below to serve that directory and proxy requests to the installed web host.

Kubernetes

See deploy/clustered/kubernetes/ for Ingress and Deployment manifests.

Proxy Configuration

Required Routes

The proxy must forward these paths to moor-web-host:

All other paths serve static web client assets.

Minimal nginx Configuration

upstream moor_api {
    server moor-web-host:8081;
}

server {
    listen 80;
    server_name your-moo.example.com;

    # Static files
    root /var/www/moor;
    index index.html;

    # SPA fallback
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API routes
    location /v1/ {
        proxy_pass http://moor_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /auth/ {
        proxy_pass http://moor_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /webhooks/ {
        proxy_pass http://moor_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Health and version
    location ~ ^/(health|version)$ {
        proxy_pass http://moor_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # WebSocket
    location /ws/ {
        proxy_pass http://moor_api;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 3600s;
    }
}

HTTPS Configuration

For HTTPS, see deploy/clustered/web-ssl/nginx-ssl.conf for an example with:

• TLS termination
• HTTP to HTTPS redirect
• Let's Encrypt certificate renewal
• Security headers

WebSocket Timeouts

WebSocket connections are long-lived. Configure appropriate timeouts:

proxy_read_timeout 3600s;  # 1 hour
proxy_send_timeout 3600s;

Development Setup

During development, Vite serves the web client and proxies API/WebSocket requests:

npm run full:dev

This starts the Vite dev server and the single-process moor server. The moor process runs the daemon, telnet host, and web host together for local development.

Vite's proxy configuration is in clients/meadow/vite.config.ts.

Environment Variables

The web client reads these at build time:

Static Asset Hosting

The web client build produces static files in dist/:

• index.html - Main entry point
• assets/ - JavaScript, CSS, images

These can be served from any static hosting (nginx, S3, CDN, etc.). The only requirement is SPA-style routing: all non-asset requests should return index.html.

Health Checks

For load balancers and orchestrators:

Related Docs

• Server Architecture
• Running a mooR Server
• Server Configuration