Rolfsvaag_Datateknikk/Lumi
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 22 Wiki Activity
0b3c8adbc2
Lumi/docs/branch-deployments.md
Franz Rolfsvaag 0b3c8adbc2 Complete experimental UX and safe branch deployments
2026-07-22 10:20:32 +02:00

4.2 KiB
Raw Blame History

Safe production branch deployments

Lumi can deploy the stable main branch or an exact published experimental-* branch from Admin > Updates > Running code branch. This is a managed deployment; Lumi does not change the live installation's Git worktree. It fetches the selected branch into data/update-cache/repo, verifies the core and bundled-plugin entry files, snapshots the running core and plugin code plus the database, replaces managed application files, records the deployed branch and commit, and then restarts.

Local data remains in place during a normal branch switch, including settings, databases, plugin data, uploads, logs, secrets, AI models/runtimes, community knowledge, corrections, and node_modules. Bundled plugin code follows the selected branch; local-only plugins absent from that branch stay installed. The update-aware wrapper repairs changed runtime dependencies before it starts the new branch.

Prerequisites

  1. Start production through npm start, npm run run, or a service that runs node run.js. The wrapper recognizes Lumi's restart exit code and starts the deployed code after dependency verification.
  2. Ensure the configured repository credential can fetch branches without an interactive password prompt.
  3. Push the experimental branch before opening the deployment control. Only main and remote branches named experimental-* are accepted.
  4. Keep snapshot retention high enough to retain at least the latest core backup. The default keeps five per target for 30 days.

Test an experimental branch

To enter from stable 0.2.24, open Admin > Settings, select Experimental as the update branch, save, and use Update from repository. The older updater installs experimental core 0.2.25; on its first startup the new guarded bootstrap confirms that an actual core update completed, snapshots the installation, synchronizes bundled plugin code, and restarts a second time. Merely checking metadata cannot trigger this bootstrap. Stable 0.2.24 predates the exact-branch picker, so it selects the newest published experimental-* branch. The same guarded entry path is available again after a return to stable. While experimental code is running, use the exact branch controls below to move between main and any published experimental branch.

  1. Open Admin > Updates and find Running code branch.
  2. Confirm the page reports the expected running branch and commit.
  3. Choose the exact experimental branch and select Deploy selected branch.
  4. Review the confirmation. Keep the page open while Lumi creates the backup, deploys, restarts gracefully, and reconnects.
  5. Verify the branch and commit after reconnection, then test the affected production workflows.

The same branch can be selected again for a verified repair deployment.

Return to stable main

Use Return safely to main. Lumi first snapshots the running experimental code, then deploys the current remote main while preserving live data. This is the preferred normal return path because it does not intentionally rewind the database or discard data written during the experiment.

Experimental database migrations must remain backward-compatible with main when this path is expected to work. Mark experimental update metadata with rollback_safe: false and document the migration when a change cannot safely be read by the stable code.

Emergency restore

Use Emergency restore previous backup only when the deployed branch cannot run correctly enough to return through the normal branch control. It restores both the previous core code and the database captured before deployment, so database changes written after that snapshot may be lost.

If the normal WebUI is unavailable, start recovery mode with LUMI_SAFE_MODE=1 npm run run, node run.js --safe-mode, or the data/recovery/safe-mode.flag marker. Recovery markers and deployment state are also visible through the production diagnostics update_state check.

Failure behavior

Fetching and target verification happen before live files are touched. Once replacement starts, failures trigger an automatic restore from the new snapshot. If automatic restore also fails, Lumi retains the recovery marker and snapshot for safe mode instead of silently continuing with a partial install.