Skip to main content

BizOSaaS Platform Deployment Runbook

Overview​

This document provides instructions for deploying and managing the BizOSaaS platform components, including the Brain Gateway, frontend portals, and integrated services (Wagtail, WordPress, etc.).

1. Staging Deployment (GitHub Actions)​

Prerequisites​

  • GitHub secrets configured:
    • DOKPLOY_API_KEY: API key for the Dokploy instance.
    • DOKPLOY_BRAIN_GATEWAY_WEBHOOK: Webhook URL for the Brain Gateway service in Dokploy.
    • GITHUB_TOKEN: (Automatic) Used to push containers to GHCR.

Procedure​

  1. Trigger via Push: Push changes to the staging or main branch.
  2. Manual Trigger:
    • Go to GitHub Actions > "Deploy to Staging".
    • Click "Run workflow".
  3. Verify: Check the Dokploy console for deployment status.

2. Manual Deployment Scripts​

Scripts Overview​

  • scripts/deploy-staging-to-dokploy.sh: Full platform staging deployment.
  • scripts/verify-cicd-setup.sh: Verify local environment before deployment.
  • scripts/generate_api_docs.py: Update API reference documentation.

Example: Running a local verification​

bash scripts/verify-cicd-setup.sh

3. Hybrid Local Bridge (Temporal & n8n)​

To optimize VPS resources, Temporal and n8n can be hosted on a local laptop and bridged to the VPS via Cloudflare Tunnels.

Prerequisites​

  • Docker & Docker Compose installed on laptop.
  • Cloudflare account with a Tunnel created.
  • CLOUDFLARE_TUNNEL_TOKEN available.

Procedure​

  1. Network Setup: 
    docker network create temporal-network
  2. Start Services: 
    docker compose -f infrastructure/compose/temporal-local.yml up -d
    docker compose -f infrastructure/compose/n8n-local.yml up -d
    docker compose -f infrastructure/compose/cloudflared.yml up -d
  3. Configure VPS Gateway:
    • Update .env.production on the VPS to point TEMPORAL_ADDRESS to temporal-bridge.bizoholic.com:7233.

4. High Availability & Resource Optimization​

The platform uses KAG (Knowledge Augmented Generation) and per-tenant rate limiting. Ensure the following:

  • KVM2 instance has at least 8GB RAM.
  • Dokploy resource limits are configured for each container.

5. Rollback Plan​

  1. In the GitHub Action, re-run a previous successful job.
  2. In Dokploy, use the "Rollback" feature to switch back to the previous image tag (staging or specific SHA).