bzl

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

SERVER_UPDATE.md (3509B)

      1 # Updating a Live Bzl Server (Git + Docker)
      2 
      3 This doc is for a typical droplet setup where you:
      4 - have the `bzlapp/Bzl` repo checked out on the server (example: `~/Bzl`)
      5 - run Bzl via Docker / Docker Compose using that checkout (builds the image from the local Dockerfile)
      6 
      7 If you’re not sure which setup you have, run `docker ps` and see whether Bzl is running as a container.
      8 
      9 ---
     10 
     11 ## The “golden” update flow (Compose + local build)
     12 
     13 From the droplet host (not inside the container):
     14 
     15 ```bash
     16 cd ~/Bzl
     17 
     18 # 1) make sure you're on the right branch and clean
     19 git status
     20 git checkout main
     21 
     22 # 2) pull latest code
     23 git fetch origin
     24 git pull --ff-only origin main
     25 
     26 # 3) rebuild + recreate container(s)
     27 docker compose up -d --build
     28 ```
     29 
     30 That’s it.
     31 
     32 ### Why this order matters
     33 - If you rebuild before pulling, you rebuild the *old* code.
     34 - A `git pull` does **not** update a running container unless you rebuild/recreate it (or you’re bind-mounting the code into the container).
     35 
     36 ---
     37 
     38 ## Restart only (no code update)
     39 
     40 ```bash
     41 docker compose restart
     42 ```
     43 
     44 Or, if you run a single container named `bzl`:
     45 
     46 ```bash
     47 docker restart bzl
     48 ```
     49 
     50 ---
     51 
     52 ## Multi-instance stack update (single host, many Bzl instances)
     53 
     54 If you run multiple Bzl instances from `multi_instance/docker-compose.yml`, use:
     55 
     56 ```bash
     57 npm run multi:update
     58 ```
     59 
     60 This script pulls latest `main`, regenerates per-instance env/compose from `multi_instance/instances.json`, and runs:
     61 
     62 ```bash
     63 docker compose -f multi_instance/docker-compose.yml up -d --build --remove-orphans
     64 ```
     65 
     66 See: `docs/MULTI_INSTANCE_DOCKER.md`
     67 
     68 ---
     69 
     70 ## Auto-detect + update all Bzl clones across server folders
     71 
     72 If your instances live in separate folders (for example one in `/Bzl` and another elsewhere), use fleet automation:
     73 
     74 ```bash
     75 # detect instances first
     76 npm run instances:scan -- --roots=/ --max-depth=4
     77 
     78 # then update all detected instances
     79 npm run instances:update -- --roots=/ --max-depth=4
     80 ```
     81 
     82 To create a brand-new instance folder:
     83 
     84 ```bash
     85 npm run instance:create -- --path=/srv/bzl-new --port=3405 --registration-code='replace-me' --hostname=new.example.com
     86 ```
     87 
     88 See: `docs/INSTANCE_FLEET_AUTOMATION.md`
     89 
     90 ---
     91 
     92 ## Common git mistake (your screenshot)
     93 
     94 If you run:
     95 
     96 ```bash
     97 git pull main
     98 ```
     99 
    100 Git interprets `main` as a *remote name* (not a branch), and you’ll get:
    101 `fatal: 'main' does not appear to be a git repository`
    102 
    103 Use this instead:
    104 
    105 ```bash
    106 git pull --ff-only origin main
    107 ```
    108 
    109 Quick sanity checks:
    110 
    111 ```bash
    112 git remote -v
    113 git branch --show-current
    114 git log -1 --oneline
    115 ```
    116 
    117 ---
    118 
    119 ## If you have local changes on the droplet
    120 
    121 If `git status` shows modified files, decide whether you want to keep them.
    122 
    123 To throw away local changes and match GitHub exactly:
    124 
    125 ```bash
    126 git fetch origin
    127 git reset --hard origin/main
    128 ```
    129 
    130 Then rebuild:
    131 
    132 ```bash
    133 docker compose up -d --build
    134 ```
    135 
    136 ---
    137 
    138 ## Confirm you’re actually updated
    139 
    140 After updating/restarting:
    141 
    142 ```bash
    143 docker ps
    144 docker logs --tail 80 bzl
    145 ```
    146 
    147 In the UI, the Moderation → Server panel should reflect the latest version string.
    148 
    149 If the UI still looks unchanged, hard-refresh your browser:
    150 - Chrome/Edge: `Ctrl+Shift+R`
    151 
    152 ---
    153 
    154 ## Next step (recommended): in-app core updates
    155 
    156 For “Clean Install” desktop setups, the Launcher UI can already do opt-in updates via GitHub Releases.
    157 
    158 For live servers, we can add a similar admin-only “Update core” flow (pull + rebuild + restart) later, but it needs extra safety:
    159 - confirmation prompts + backup
    160 - clear logs of what changed
    161 - no “surprise” updates