Deploying a Multi‑Tenant Rating API on UBOS with OpenClaw – Step‑by‑Step Guide

3.1 Installing UBOS

UBOS can be installed on any Linux VM, on‑premise hardware, or via a cloud marketplace image. Follow the official UBOS solutions for SMBs guide for a quick spin‑up:

1. Download the UBOS installer script:

curl -sSL https://ubos.tech/install.sh | bash

2. Run the installer and accept the default configuration (UBOS will set up Docker, a reverse proxy, and a basic monitoring stack).
3. Log in to the UBOS dashboard at https://<your‑domain>/admin using the credentials generated during installation.

3.2 Deploying the OpenClaw App

OpenClaw is offered as a pre‑packaged UBOS app. To provision it:

1. Navigate to Apps → Marketplace in the UBOS UI.
2. Search for “OpenClaw” and click Install. The platform will pull the Docker image, create a service, and expose it on a sub‑domain like openclaw.your‑domain.com.
3. During installation, select a database backend (PostgreSQL is recommended for its JSONB support).
4. After deployment, verify the service health by visiting the OpenClaw UI; you should see the default “Hello OpenClaw” page.

For a deeper dive into the provisioning process, see the OpenClaw hosting guide on UBOS.

4.1 Enabling Multi‑Tenant Mode

Edit the rating-plugin.yaml configuration file located at /var/ubos/apps/openclaw/config/:

plugin:
  name: rating
  multiTenant: true
  tenantKey: X-Tenant-ID   # HTTP header used to identify the tenant

Setting multiTenant: true tells OpenClaw to enforce tenant isolation on every request.

4.2 Setting Tenant Identifiers

Each SaaS customer must be assigned a unique identifier (e.g., a UUID). Store these IDs in a Tenant Registry table within your primary database:

When a client calls the rating API, it must include the header X‑Tenant‑ID: <tenant_id>. OpenClaw validates the header against the registry and automatically scopes all CRUD operations to that tenant’s data partition.

5.1 Building the API Container

Create a new directory rating-api/ and add a minimal Dockerfile:

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
EXPOSE 8080
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

In requirements.txt include fastapi, uvicorn, and openclaw-sdk. The main.py file should instantiate the OpenClaw client, read the X‑Tenant‑ID header, and forward rating requests to the OpenClaw rating plugin.

Build the image locally:

docker build -t ubos/rating-api:latest .

5.2 Deploying via UBOS Services

Push the image to a container registry accessible by UBOS (Docker Hub, GitHub Packages, or a private registry). Then create a UBOS service definition:

name: rating-api
image: ubos/rating-api:latest
replicas: 3
ports:
  - containerPort: 8080
    protocol: TCP
    expose: true
environment:
  - OPENCLAW_URL=https://openclaw.your-domain.com
  - DATABASE_URL=postgres://user:pass@db.your-domain.com:5432/openclaw

Upload this YAML via the UBOS UI under Services → Create Service. UBOS will schedule three replicas behind its built‑in load balancer, automatically handling scaling and health checks.

For a visual walkthrough of UBOS service creation, explore the Workflow automation studio which can generate the YAML from a drag‑and‑drop flow.

6.1 Health Checks

UBOS automatically creates a /healthz endpoint for each service. Test it with curl:

curl -s https://rating-api.your-domain.com/healthz | jq

A successful response looks like:

{ "status": "ok", "uptime": "12h34m" }

6.2 Sample API Calls per Tenant

Assume two tenants with IDs 1111‑aaaa‑bbbb‑cccc and 2222‑dddd‑eeee‑ffff. Submit a rating for a product (product ID prod‑123) as Tenant 1:

curl -X POST https://rating-api.your-domain.com/rate \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 1111-aaaa-bbbb-cccc" \
  -d '{"product_id":"prod-123","score":4.5,"comment":"Great!"}'

Now submit a rating for the same product as Tenant 2:

curl -X POST https://rating-api.your-domain.com/rate \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 2222-dddd-eeee-ffff" \
  -d '{"product_id":"prod-123","score":2.0,"comment":"Not what I expected."}'

When you query the average rating for prod‑123 without a tenant header, OpenClaw returns a global view (which you can disable). To see tenant‑specific aggregates, include the header:

curl -s https://rating-api.your-domain.com/average?product_id=prod-123 \
  -H "X-Tenant-ID: 1111-aaaa-bbbb-cccc" | jq

The response will reflect only Tenant 1’s data, confirming proper isolation.