bzl

self-hosted ephemeral community engine
Log | Files | Refs | README | LICENSE

MULTI_INSTANCE_DOCKER.md (2576B)

      1 # Multi-instance Docker Setup (Single Server)
      2 
      3 This workflow lets you run multiple Bzl instances on one host, each with its own:
      4 - persistent data volume
      5 - hostname
      6 - registration code
      7 
      8 It also supports generating Cloudflare tunnel ingress config and optional automated `cloudflared tunnel route dns` calls.
      9 
     10 ---
     11 
     12 ## 1) Create/edit config
     13 
     14 Run once:
     15 
     16 ```bash
     17 npm run multi:init
     18 ```
     19 
     20 If `multi_instance/instances.json` does not exist, the script creates a template and exits.
     21 
     22 Edit:
     23 - `multi_instance/instances.json`
     24 
     25 Key fields:
     26 - `instances[].id` - stable identifier (used for service/env filenames)
     27 - `instances[].hostname` - public hostname for that instance
     28 - `instances[].hostPort` - unique localhost port each instance maps to
     29 - `instances[].registrationCode` - per-instance registration code
     30 - `cloudflared.*` - tunnel config + optional DNS route automation
     31 
     32 ---
     33 
     34 ## 2) Generate compose + env + DNS checklist
     35 
     36 ```bash
     37 npm run multi:init
     38 ```
     39 
     40 Generated files:
     41 - `multi_instance/docker-compose.yml`
     42 - `multi_instance/env/<id>.env` (one per instance)
     43 - `multi_instance/DNS_CHECKLIST.md`
     44 - Cloudflared config (path from `cloudflared.configPath`, default `~/.cloudflared/config.yml`)
     45 
     46 Optional DNS automation:
     47 
     48 ```bash
     49 npm run multi:init -- --route-dns
     50 ```
     51 
     52 This runs `cloudflared tunnel route dns ...` for each configured hostname.
     53 
     54 ---
     55 
     56 ## 3) Start all instances
     57 
     58 ```bash
     59 docker compose -f multi_instance/docker-compose.yml up -d --build --remove-orphans
     60 ```
     61 
     62 Then verify local health endpoints from the host:
     63 
     64 ```bash
     65 curl -fsS http://127.0.0.1:<hostPort>/api/health
     66 ```
     67 
     68 ---
     69 
     70 ## 4) Update all instances to latest source-of-truth
     71 
     72 Use the updater script from the repo root:
     73 
     74 ```bash
     75 npm run multi:update
     76 ```
     77 
     78 Default behavior:
     79 1. `git fetch origin`
     80 2. `git checkout main`
     81 3. `git pull --ff-only origin main`
     82 4. regenerate multi-instance config outputs
     83 5. `docker compose -f multi_instance/docker-compose.yml up -d --build --remove-orphans`
     84 
     85 Options:
     86 - `--skip-git` (skip fetch/pull)
     87 - `--skip-build` (restart/update without image rebuild)
     88 - `--route-dns` (also rerun DNS route commands during regeneration)
     89 - `--dry-run` (show the docker command without executing it)
     90 - `--config=/path/to/instances.json`
     91 
     92 ---
     93 
     94 ## DNS reminders
     95 
     96 After generating or changing hostnames:
     97 - ensure each hostname is routed to the intended tunnel (`cloudflared tunnel route dns ...`)
     98 - confirm Cloudflare SSL/TLS mode is compatible (Full / Full strict recommended)
     99 - restart tunnel process/service if ingress config changed
    100 - verify each hostname reaches the expected instance (`/api/health`)