Skip to main content

Infrastructure Runbook: OxaWay

Version: 1.2 (Pilot Phase Config) Last Updated: 5 February 2026 Status: MVP / Pilot Ready

1. Overview & Strategy​

This document tracks the manual steps required to provision, configure, and deploy the production infrastructure for OxaWay.

  • Provider: Hetzner Cloud (Falkenstein/Nuremberg)
  • Orchestrator: Coolify (Self-Hosted PaaS)
  • Domain Management: AWS Route 53
  • Core Stack: Typebot (Chat), Flowise (AI), Supabase (External DB), Trigger.dev (Cloud for MVP).

1.1 System Architecture Diagram​

The following diagram illustrates the Hybrid Cloud topology. Note the single Hetzner node acting as the central hub for the Pilot phase.

⚠️ Architecture Decision Log (Pilot Phase Constraints)​

The following trade-offs have been explicitly accepted for the Summer 2026 Pilot:

  1. Single Point of Failure: We run on a single VPS. Hardware failure will result in downtime until manual recovery.
  2. Deployment Downtime: Rolling updates are not configured. Expect 10-30s of 502 errors during service deployments.
  3. Data RPO: Backups are Daily. Up to 24h of data loss is acceptable for this phase.
  4. Latency: Cross-region latency (Trigger.dev US < - > Hetzner EU) is accepted.

2. Server Provisioning (Hetzner)​

2.1 Machine Selection​

We choose Hetzner for GDPR compliance and price-to-performance ratio.

  • Login to Hetzner Cloud Console.
  • Create Project: Name it Oxa-Production.
  • Add Server:
    • Location: Falkenstein or Nuremberg (Germany).
    • Image: Ubuntu 24.04 LTS (Architecture: x86).
    • Type: CPX31 (4 vCPU, 8 GB RAM) - Baseline.
    • Networking: Select IPv4 and IPv6.
    • SSH Key: Add your local machine's public SSH key.
    • Name: oxa-prod-01
  • Create & Buy.
  • Copy IP Address: (e.g., 89.167.xx.xx) - We will refer to this as $SERVER_IP.

3. Orchestrator Setup (Coolify)​

3.1 Installation​

  • SSH into Server: ssh root@$SERVER_IP
  • Run Install Script: 
    curl -fsSL [https://cdn.coollabs.io/coolify/install.sh](https://cdn.coollabs.io/coolify/install.sh) | bash
  • Access Dashboard: Open http://$SERVER_IP:8000.
  • Create Admin Account: Register your root admin user.

4. Service Deployment & Configuration​

4.1 Global Secret Management (MANDATORY)​

Security Rule: NEVER commit .env files to the repository. All secrets must be injected at runtime.

  • In Coolify, for every service (Typebot, Flowise, Next.js), navigate to Settings -> Environment Variables.
  • Paste keys here. They will be encrypted and injected into the container.

4.2 Typebot (Chat Interface)​

  • Create Service: In Coolify, create a Docker Compose with the below code:
version: "3.8"

services:
  typebot-builder:
    image: baptistearno/typebot-builder:latest
    restart: always
    environment:
      - DATABASE_URL=${SUPABASE_DATABASE_URL}
      - NEXTAUTH_URL=${BUILDER_URL}
      - NEXT_PUBLIC_VIEWER_URL=${VIEWER_URL}
      - ENCRYPTION_SECRET=${ENCRYPTION_SECRET}
      - ADMIN_EMAIL=${ADMIN_EMAIL}
      # Auth Providers (Required for B2B Dashboard access)
      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
    networks:
      - coolify
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.typebot-builder.rule=Host(`bot.oxaway.ai`)"
      - "traefik.http.routers.typebot-builder.entrypoints=websecure"
      - "traefik.http.routers.typebot-builder.tls.certresolver=letsencrypt"
      - "traefik.http.services.typebot-builder.loadbalancer.server.port=3000"
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/health || exit 1"]

  typebot-viewer:
    image: baptistearno/typebot-viewer:latest
    restart: always
    environment:
      - DATABASE_URL=${SUPABASE_DATABASE_URL}
      - NEXT_PUBLIC_VIEWER_URL=${VIEWER_URL}
      - ENCRYPTION_SECRET=${ENCRYPTION_SECRET}
      - NEXTAUTH_URL=${NEXTAUTH_URL}
    networks:
      - coolify
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.typebot-viewer.rule=Host(`chat.oxaway.ai`)"
      - "traefik.http.routers.typebot-viewer.entrypoints=websecure"
      - "traefik.http.routers.typebot-viewer.tls.certresolver=letsencrypt"
      - "traefik.http.services.typebot-viewer.loadbalancer.server.port=3000"
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/health || exit 1"]
networks:
  coolify:
    external: true

📝 OxaWay Typebot Deployment Config​

# --- DATABASE ---
# Direct connection to Supabase (Use the Transaction pooler if possible)
SUPABASE_DATABASE_URL="postgresql://postgres.drcnpttbfutxcnolhzhh:[YOUR-PASSWORD]@aws-1-eu-west-1.pooler.supabase.com:5432/postgres"

# --- SECRETS ---
# Use 'openssl rand -base64 32' to generate
ENCRYPTION_SECRET="REPLACE_WITH_A_SECURE_LONG_STRING"

# --- NETWORKING ---
# Ensure these domains are created in Route 53 first
BUILDER_URL="https://typebot.oxaway.ai"
VIEWER_URL="https://chat.oxaway.ai"
NEXTAUTH_URL="https://typebot.oxaway.ai"

# --- BRANDING & ACCESS ---
# Only users with this email can access the 'Builder' initially
ADMIN_EMAIL="[EMAIL_ADDRESS]"
DISABLE_SIGNUP=true

# --- OPTIONAL: S3 STORAGE (For guest uploads) ---
# S3_ENDPOINT="https://[id].r2.cloudflarestorage.com"
# S3_ACCESS_KEY="your-key"
# S3_SECRET_KEY="your-secret"
# S3_BUCKET="oxaway-assets"

For ENCRYPTION_SECRET use: openssl rand -hex 16

4.3 Flowise (AI Logic) - With Resource Limits​

Flowise is memory/CPU intensive. We limit it to prevent it from crashing the Chat Interface.

  • Create Service: In Coolify, select Flowise.
  • Domain Config: Set URL to https://flowise.oxaway.ai:3001.
  • Docker Compose Modification:
    • Go to the "Docker Compose" tab in Coolify for the Flowise service.
    • Add the deploy block to the Flowise service definition:
    services:
      flowise:
        image: flowiseai/flowise:latest
        restart: always
        deploy:
          resources:
            limits:
              cpus: "1.5" # Limit to 1.5 cores (leaves 2.5 for Typebot/OS)
              memory: 3072M # Limit to 3GB RAM
        environment:
          - DATABASE_PATH=/root/.flowise
          - FLOWISE_USERNAME=admin
          - FLOWISE_PASSWORD=[SetInEnvVars]
  • Deploy.

4.4 Trigger.dev (Cloud Setup)​

  • Sign Up: Go to cloud.trigger.dev.
  • Create Organization: "OxaWay".
  • Create Project: "Oxa Prod".
  • Get Keys: Project Settings -> API Keys.
  • Action: Copy TRIGGER_SECRET_KEY.
  • Injection: Go to Coolify -> Your Next.js Dashboard Service -> Environment Variables. Add TRIGGER_SECRET_KEY there. Do not put this in your local code.

5. Security & Maintenance​

5.1 Firewall (Hetzner)​

Do not rely solely on the OS firewall. Use Hetzner's Cloud Firewall.

  • Go to Hetzner Console -> Firewalls.
  • Create "Web-Server" Rule:
    • Inbound:
      • TCP Port 22 (SSH) - Optional: Restrict to your home IP.
      • TCP Port 80 (HTTP) - Any IPv4/IPv6.
      • TCP Port 443 (HTTPS) - Any IPv4/IPv6.
      • UDP Port 443 (HTTP/3) - Any IPv4/IPv6.
    • Outbound: Allow all.
  • Apply to Server: oxa-prod-01.

5.2 Backups (Pilot Strategy)​

  • Configure Coolify Backups:
    • Go to Coolify Settings -> Backups.
    • Connect an S3 Bucket (AWS S3, Cloudflare R2, or Hetzner Storage Box).
    • Schedule: 0 2 * * * (Daily at 2 AM).
    • Note: We accept a Recovery Point Objective (RPO) of 24 hours for the Pilot.
  • Verify: Manually trigger a backup and check the S3 bucket content.

6. Domain & DNS (AWS Route 53)​

  • Log in to AWS Console -> Route 53.
  • Select Zone: oxaway.ai.
  • Create A Records:
    • panel.oxaway.ai -> $SERVER_IP (Coolify)
    • bot.oxaway.ai -> $SERVER_IP (Typebot)
    • flowise.oxaway.ai -> $SERVER_IP (Flowise)