Self-Hosting

Complete instructions for deploying OFFER-HUB Orchestrator on your own infrastructure using Docker.

Run OFFER-HUB Orchestrator on your own server with full control over data, uptime, and configuration. This guide covers everything from initial setup to ongoing maintenance using Docker.

Tip

If you haven't configured your environment variables yet, review the Configuration page first.

Prerequisites

Before you begin, make sure your host machine meets the following requirements:

Docker v20.10 or later
Docker Compose v2.0 or later
PostgreSQL 15+ (or managed service like Supabase, Neon, Railway)
Redis 7+ (or managed service like Upstash, Railway)
A registered domain name (recommended for production)
At least 2 GB of RAM and 20 GB of disk space

Verify that Docker is installed and running:

docker --version && docker compose version

Note

On older installations you may need to use docker-compose (with a hyphen) instead of docker compose.

Architecture Overview

The repository's root Compose file starts only the infrastructure dependencies. The API is built and run from the repository separately:

Mermaid

Rendering diagram…

The API runs alongside PostgreSQL and Redis, and connects to the Stellar network.

The topology is verified against the Orchestrator root docker-compose.yml, apps/api/src/main.ts, and apps/api/src/modules/webhooks/webhooks.controller.ts: Compose provides PostgreSQL and Redis while the API hosts both REST endpoints and inbound webhook handling.

Docker Setup

Project Structure

Create a deployment directory:

mkdir offer-hub-deploy && cd offer-hub-deploy

Your directory will contain:

typescript

offer-hub-deploy/
├── docker-compose.yml
├── .env
├── nginx.conf (optional)
└── certs/ (optional, for TLS)

docker-compose.yml

Create a docker-compose.yml file:

yaml

version: "3.9"

services:
  postgres:
    image: postgres:15-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: offerhub
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-offerhub_secret}
      POSTGRES_DB: offerhub_db
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U offerhub"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - offerhub

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
volumes:
  postgres_data:
  redis_data:

Warning

This Compose file provides PostgreSQL and Redis only. Run the API from the repository with the commands below, or deploy it with a build-based platform configuration.

Using External Services

If you prefer managed databases, remove postgres and redis services and update the environment:

yaml

services:
  postgres:
    image: postgres:15-alpine
  redis:
    image: redis:7-alpine

Building and running the API from source

Clone the source repository, install its dependencies, and run the API directly. No published application images are required.

git clone https://github.com/OFFER-HUB/OFFER-HUB.git && cd OFFER-HUB

npm ci && npm run build && npm start -w @offerhub/api

Environment Variables

Create a .env file in the same directory as your docker-compose.yml.

Required Variables

Variable	Description
`NODE_ENV`	Runtime environment: `development`, `staging`, `production`
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string
`OFFERHUB_MASTER_KEY`	Master key for creating API keys
`WALLET_ENCRYPTION_KEY`	64 hex chars - AES-256-GCM key for wallet encryption
`TRUSTLESS_API_KEY`	Trustless Work API key for escrow
`PLATFORM_USER_ID`	Platform user ID for escrow operations
`PUBLIC_BASE_URL`	Your Orchestrator's public URL

Optional Variables

Variable	Default	Description
`PORT`	`4000`	HTTP server port
`LOG_LEVEL`	`info`	Logging level: `debug`, `info`, `warn`, `error`
`PAYMENT_PROVIDER`	`crypto`	Payment mode for the `PaymentProvider` strategy. Only `crypto` is implemented — `airtm` throws at startup
`STELLAR_NETWORK`	`testnet`	Stellar network: `testnet` or `mainnet`
`STELLAR_USDC_ISSUER`	Testnet issuer	USDC asset issuer address

Danger

Never commit your .env file to version control. Treat every value as a secret.

Example .env File

bash

# Server
NODE_ENV=production
PORT=4000
LOG_LEVEL=info

# Database (PostgreSQL)
DATABASE_URL=postgresql://offerhub:your_password@postgres:5432/offerhub_db
POSTGRES_PASSWORD=your_password

# Redis
REDIS_URL=redis://redis:6379

# Authentication
OFFERHUB_MASTER_KEY=your-secure-master-key-at-least-32-chars

# Payment Provider
PAYMENT_PROVIDER=crypto
WALLET_ENCRYPTION_KEY=your-64-character-hex-key-here-generate-with-crypto-randomBytes

# Trustless Work (Escrow)
TRUSTLESS_API_KEY=your_trustless_api_key
TRUSTLESS_WEBHOOK_SECRET=your_webhook_secret

# Platform Identity
PLATFORM_USER_ID=usr_platform

# Stellar
STELLAR_NETWORK=mainnet
STELLAR_USDC_ISSUER=GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

# Public URL
PUBLIC_BASE_URL=https://api.yourdomain.com

# Frontend (if running frontend in same compose)
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_STELLAR_NETWORK=mainnet

Generating Secure Keys

bash

# Generate OFFERHUB_MASTER_KEY
openssl rand -base64 32

# Generate WALLET_ENCRYPTION_KEY (64 hex characters)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Running in Production

Starting the Stack

Once your .env file is ready, bring everything up in detached mode:

docker compose up -d

Watch the logs to confirm all services start cleanly:

docker compose logs -f

Running Database Migrations

Apply Prisma migrations before the first launch (or after pulling a new source revision):

npm run prisma:generate && npx prisma migrate deploy --schema packages/database/prisma/schema.prisma

Tip

To understand exactly what gets created — every table, field, and relationship — see the Data Model reference.

Warning

Always back up your database before running migrations in production.

Setting NODE_ENV

Make sure NODE_ENV=production is set in your .env file. This enables:

Optimised builds and minification
Stricter error handling
Disabled development-only logging
Production-level security defaults

TLS / HTTPS

For production deployments you should terminate TLS at your hosting platform or an external reverse proxy. The dependency Compose file does not include an application or proxy service.

Example nginx.conf:

nginx

events {
    worker_connections 1024;
}

http {
    upstream orchestrator {
        server orchestrator:4000;
    }

    upstream frontend {
        server frontend:3000;
    }

    server {
        listen 80;
        server_name yourdomain.com;
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl;
        server_name yourdomain.com;

        ssl_certificate /etc/nginx/certs/fullchain.pem;
        ssl_certificate_key /etc/nginx/certs/privkey.pem;

        # API routes
        location /api {
            proxy_pass http://orchestrator;
            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_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        # Frontend routes
        location / {
            proxy_pass http://frontend;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
        }
    }
}

Tip

Let's Encrypt with Certbot is the easiest way to obtain free TLS certificates.

Health Checks

The Orchestrator exposes a /health endpoint that returns the current service status. The Docker Compose file already configures a health check against it.

Manual Check

curl http://localhost:4000/health

Expected response:

json

{
  "status": "ok",
  "timestamp": "2026-02-25T12:00:00.000Z",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "stellar": "connected"
  }
}

Container Health Status

Docker reports health status directly:

docker compose ps

A healthy deployment shows (healthy) next to each service. If a service is (unhealthy), inspect its logs:

docker compose logs orchestrator --tail 50

Monitoring Tips

Point an uptime monitor (e.g. UptimeRobot, Betterstack) at /health.
Set up alerts for non-200 responses or response times above 2 seconds.
Monitor disk usage — logs, database, and Docker images can accumulate over time.
Track Redis memory usage — BullMQ jobs can grow if not cleaned up.

Background Jobs

The Orchestrator uses BullMQ for background job processing:

Queue	Purpose
`webhooks`	Process inbound provider webhooks (AirTM, Trustless Work)
`reconciliation`	Periodic sync jobs with external providers
`notifications`	Send notifications (email, push, etc.)
`dead-letter-queue`	Jobs that exhausted all retry attempts

Monitor job queues:

bash

# View Redis keys
docker compose exec redis redis-cli keys "bull:*"

# Check queue length
docker compose exec redis redis-cli llen "bull:webhooks:wait"

Updating

Updating the source and infrastructure

git pull --ff-only

Applying the Update

docker compose up -d

This starts or updates the PostgreSQL and Redis dependencies. Rebuild and restart the API separately.

Full Update Workflow

The recommended update procedure:

Back up your database before any update.
Pull the latest source.
Run migrations.
Rebuild and restart the API.

bash

# 1. Backup database
docker compose exec postgres pg_dump -U offerhub offerhub_db > backup-$(date +%Y%m%d).sql

# 2. Pull the latest source
git pull --ff-only

# 3. Rebuild the API
npm ci && npm run build

# 4. Run any new migrations
npx prisma migrate deploy --schema packages/database/prisma/schema.prisma

# 5. Verify health
curl http://localhost:4000/api/v1/health

Rolling Back

If something goes wrong, roll back the source checkout to a known-good commit:

bash

git log --oneline -10
git checkout <known-good-commit>
npm ci && npm run build

Then restart the API:

npm start -w @offerhub/api

Security Checklist

Before going to production, verify:

NODE_ENV=production is set
OFFERHUB_MASTER_KEY is a strong, unique value
WALLET_ENCRYPTION_KEY is backed up securely
Database uses SSL (?sslmode=require)
Redis uses TLS (rediss://)
HTTPS is enabled with valid certificates
Firewall only exposes ports 80/443
Database is not publicly accessible
Redis is not publicly accessible
Inbound webhook secrets are configured (AIRTM_WEBHOOK_SECRET / TRUSTLESS_WEBHOOK_SECRET)

Troubleshooting

API won't start

bash

# Check logs
npm start -w @offerhub/api

# Common issues:
# - DATABASE_URL invalid
# - WALLET_ENCRYPTION_KEY wrong length
# - Redis not reachable

Database connection errors

bash

# Test PostgreSQL connection
npx prisma db pull --schema packages/database/prisma/schema.prisma

# Check if migrations are applied
npx prisma migrate status --schema packages/database/prisma/schema.prisma

Inbound provider webhooks not being processed

bash

# Check the inbound webhook queue
docker compose exec redis redis-cli lrange "bull:webhooks:failed" 0 10

# Common issues:
# - AIRTM_WEBHOOK_SECRET / TRUSTLESS_WEBHOOK_SECRET don't match the provider's configured secret
# - The provider can't reach POST /api/v1/webhooks/airtm or /api/v1/webhooks/trustless-work
#   (PUBLIC_BASE_URL wrong, firewall, or TLS misconfiguration)

Next Steps

Configuration — Full environment variable reference
Quick Start — Make your first API call
Data Model — Every database table and relationship
API Reference — Explore all endpoints
Events (SSE) — SSE event stream and event catalog

Edit this page on GitHub

Self-Hosting

Complete instructions for deploying OFFER-HUB Orchestrator on your own infrastructure using Docker.

Run OFFER-HUB Orchestrator on your own server with full control over data, uptime, and configuration. This guide covers everything from initial setup to ongoing maintenance using Docker.

Tip

If you haven't configured your environment variables yet, review the Configuration page first.

Prerequisites

Before you begin, make sure your host machine meets the following requirements:

Docker v20.10 or later
Docker Compose v2.0 or later
PostgreSQL 15+ (or managed service like Supabase, Neon, Railway)
Redis 7+ (or managed service like Upstash, Railway)
A registered domain name (recommended for production)
At least 2 GB of RAM and 20 GB of disk space

Verify that Docker is installed and running:

docker --version && docker compose version

Note

On older installations you may need to use docker-compose (with a hyphen) instead of docker compose.

Architecture Overview

The repository's root Compose file starts only the infrastructure dependencies. The API is built and run from the repository separately:

Mermaid

Rendering diagram…

The API runs alongside PostgreSQL and Redis, and connects to the Stellar network.

Docker Setup

Project Structure

Create a deployment directory:

mkdir offer-hub-deploy && cd offer-hub-deploy

Your directory will contain:

typescript

offer-hub-deploy/
├── docker-compose.yml
├── .env
├── nginx.conf (optional)
└── certs/ (optional, for TLS)

docker-compose.yml

Create a docker-compose.yml file:

yaml

version: "3.9"

services:
  postgres:
    image: postgres:15-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: offerhub
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-offerhub_secret}
      POSTGRES_DB: offerhub_db
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U offerhub"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - offerhub

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
volumes:
  postgres_data:
  redis_data:

Warning

This Compose file provides PostgreSQL and Redis only. Run the API from the repository with the commands below, or deploy it with a build-based platform configuration.

Using External Services

If you prefer managed databases, remove postgres and redis services and update the environment:

yaml

services:
  postgres:
    image: postgres:15-alpine
  redis:
    image: redis:7-alpine

Building and running the API from source

Clone the source repository, install its dependencies, and run the API directly. No published application images are required.

git clone https://github.com/OFFER-HUB/OFFER-HUB.git && cd OFFER-HUB

npm ci && npm run build && npm start -w @offerhub/api

Environment Variables

Create a .env file in the same directory as your docker-compose.yml.

Required Variables

Variable	Description
`NODE_ENV`	Runtime environment: `development`, `staging`, `production`
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string
`OFFERHUB_MASTER_KEY`	Master key for creating API keys
`WALLET_ENCRYPTION_KEY`	64 hex chars - AES-256-GCM key for wallet encryption
`TRUSTLESS_API_KEY`	Trustless Work API key for escrow
`PLATFORM_USER_ID`	Platform user ID for escrow operations
`PUBLIC_BASE_URL`	Your Orchestrator's public URL

Optional Variables

Variable	Default	Description
`PORT`	`4000`	HTTP server port
`LOG_LEVEL`	`info`	Logging level: `debug`, `info`, `warn`, `error`
`PAYMENT_PROVIDER`	`crypto`	Payment mode for the `PaymentProvider` strategy. Only `crypto` is implemented — `airtm` throws at startup
`STELLAR_NETWORK`	`testnet`	Stellar network: `testnet` or `mainnet`
`STELLAR_USDC_ISSUER`	Testnet issuer	USDC asset issuer address

Danger

Never commit your .env file to version control. Treat every value as a secret.

Example .env File

bash

# Server
NODE_ENV=production
PORT=4000
LOG_LEVEL=info

# Database (PostgreSQL)
DATABASE_URL=postgresql://offerhub:your_password@postgres:5432/offerhub_db
POSTGRES_PASSWORD=your_password

# Redis
REDIS_URL=redis://redis:6379

# Authentication
OFFERHUB_MASTER_KEY=your-secure-master-key-at-least-32-chars

# Payment Provider
PAYMENT_PROVIDER=crypto
WALLET_ENCRYPTION_KEY=your-64-character-hex-key-here-generate-with-crypto-randomBytes

# Trustless Work (Escrow)
TRUSTLESS_API_KEY=your_trustless_api_key
TRUSTLESS_WEBHOOK_SECRET=your_webhook_secret

# Platform Identity
PLATFORM_USER_ID=usr_platform

# Stellar
STELLAR_NETWORK=mainnet
STELLAR_USDC_ISSUER=GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

# Public URL
PUBLIC_BASE_URL=https://api.yourdomain.com

# Frontend (if running frontend in same compose)
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_STELLAR_NETWORK=mainnet

Generating Secure Keys

bash

# Generate OFFERHUB_MASTER_KEY
openssl rand -base64 32

# Generate WALLET_ENCRYPTION_KEY (64 hex characters)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Running in Production

Starting the Stack

Once your .env file is ready, bring everything up in detached mode:

docker compose up -d

Watch the logs to confirm all services start cleanly:

docker compose logs -f

Running Database Migrations

Apply Prisma migrations before the first launch (or after pulling a new source revision):

npm run prisma:generate && npx prisma migrate deploy --schema packages/database/prisma/schema.prisma

Tip

To understand exactly what gets created — every table, field, and relationship — see the Data Model reference.

Warning

Always back up your database before running migrations in production.

Setting NODE_ENV

Make sure NODE_ENV=production is set in your .env file. This enables:

Optimised builds and minification
Stricter error handling
Disabled development-only logging
Production-level security defaults

TLS / HTTPS

For production deployments you should terminate TLS at your hosting platform or an external reverse proxy. The dependency Compose file does not include an application or proxy service.

Example nginx.conf:

nginx

events {
    worker_connections 1024;
}

http {
    upstream orchestrator {
        server orchestrator:4000;
    }

    upstream frontend {
        server frontend:3000;
    }

    server {
        listen 80;
        server_name yourdomain.com;
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl;
        server_name yourdomain.com;

        ssl_certificate /etc/nginx/certs/fullchain.pem;
        ssl_certificate_key /etc/nginx/certs/privkey.pem;

        # API routes
        location /api {
            proxy_pass http://orchestrator;
            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_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        # Frontend routes
        location / {
            proxy_pass http://frontend;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
        }
    }
}

Tip

Let's Encrypt with Certbot is the easiest way to obtain free TLS certificates.

Health Checks

The Orchestrator exposes a /health endpoint that returns the current service status. The Docker Compose file already configures a health check against it.

Manual Check

curl http://localhost:4000/health

Expected response:

json

{
  "status": "ok",
  "timestamp": "2026-02-25T12:00:00.000Z",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "stellar": "connected"
  }
}

Container Health Status

Docker reports health status directly:

docker compose ps

A healthy deployment shows (healthy) next to each service. If a service is (unhealthy), inspect its logs:

docker compose logs orchestrator --tail 50

Monitoring Tips

Point an uptime monitor (e.g. UptimeRobot, Betterstack) at /health.
Set up alerts for non-200 responses or response times above 2 seconds.
Monitor disk usage — logs, database, and Docker images can accumulate over time.
Track Redis memory usage — BullMQ jobs can grow if not cleaned up.

Background Jobs

The Orchestrator uses BullMQ for background job processing:

Queue	Purpose
`webhooks`	Process inbound provider webhooks (AirTM, Trustless Work)
`reconciliation`	Periodic sync jobs with external providers
`notifications`	Send notifications (email, push, etc.)
`dead-letter-queue`	Jobs that exhausted all retry attempts

Monitor job queues:

bash

# View Redis keys
docker compose exec redis redis-cli keys "bull:*"

# Check queue length
docker compose exec redis redis-cli llen "bull:webhooks:wait"

Updating

Updating the source and infrastructure

git pull --ff-only

Applying the Update

docker compose up -d

This starts or updates the PostgreSQL and Redis dependencies. Rebuild and restart the API separately.

Full Update Workflow

The recommended update procedure:

Back up your database before any update.
Pull the latest source.
Run migrations.
Rebuild and restart the API.

bash

# 1. Backup database
docker compose exec postgres pg_dump -U offerhub offerhub_db > backup-$(date +%Y%m%d).sql

# 2. Pull the latest source
git pull --ff-only

# 3. Rebuild the API
npm ci && npm run build

# 4. Run any new migrations
npx prisma migrate deploy --schema packages/database/prisma/schema.prisma

# 5. Verify health
curl http://localhost:4000/api/v1/health

Rolling Back

If something goes wrong, roll back the source checkout to a known-good commit:

bash

git log --oneline -10
git checkout <known-good-commit>
npm ci && npm run build

Then restart the API:

npm start -w @offerhub/api

Security Checklist

Before going to production, verify:

NODE_ENV=production is set
OFFERHUB_MASTER_KEY is a strong, unique value
WALLET_ENCRYPTION_KEY is backed up securely
Database uses SSL (?sslmode=require)
Redis uses TLS (rediss://)
HTTPS is enabled with valid certificates
Firewall only exposes ports 80/443
Database is not publicly accessible
Redis is not publicly accessible
Inbound webhook secrets are configured (AIRTM_WEBHOOK_SECRET / TRUSTLESS_WEBHOOK_SECRET)

Troubleshooting

API won't start

bash

# Check logs
npm start -w @offerhub/api

# Common issues:
# - DATABASE_URL invalid
# - WALLET_ENCRYPTION_KEY wrong length
# - Redis not reachable

Database connection errors

bash

# Test PostgreSQL connection
npx prisma db pull --schema packages/database/prisma/schema.prisma

# Check if migrations are applied
npx prisma migrate status --schema packages/database/prisma/schema.prisma

Inbound provider webhooks not being processed

bash

# Check the inbound webhook queue
docker compose exec redis redis-cli lrange "bull:webhooks:failed" 0 10

# Common issues:
# - AIRTM_WEBHOOK_SECRET / TRUSTLESS_WEBHOOK_SECRET don't match the provider's configured secret
# - The provider can't reach POST /api/v1/webhooks/airtm or /api/v1/webhooks/trustless-work
#   (PUBLIC_BASE_URL wrong, firewall, or TLS misconfiguration)

Next Steps

Configuration — Full environment variable reference
Quick Start — Make your first API call
Data Model — Every database table and relationship
API Reference — Explore all endpoints
Events (SSE) — SSE event stream and event catalog

Edit this page on GitHub