fix(gallery): make backend (re)install a clean replace instead of an overlay#10726
Merged
Conversation
…overlay InstallBackend extracted the artifact directly into the target directory with no pre-clean, so a reinstall overlaid the new files onto the old ones. Files present in a previous version but absent in the new artifact (a stale .so, an orphaned package dir) survived and could shadow the new build at import time -- e.g. an old vllm shared object lingering next to a freshly pulled one. Only a failed download cleaned the directory. Stage the download/extraction into a `<name>.install-tmp` dir, validate run.sh is present, write metadata, then atomically swap it into place (rename current -> .install-backup, staging -> current, drop backup), rolling back on failure. This mirrors the atomic swap UpgradeBackend already performs, so install and upgrade now leave identical on-disk state with no orphaned files. Reported as part of #10720. Signed-off-by: Ettore Di Giacinto <mudler@localai.io> Assisted-by: Claude:claude-opus-4-8 [Claude Code]
mudler
approved these changes
Jul 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
InstallBackendnow stages the download/extraction into a<name>.install-tmpdir, validatesrun.sh, writes metadata, then atomically swaps it into place (rename current →.install-backup, staging → current, drop backup) with rollback on failure — mirroring the atomic swapUpgradeBackendalready performs.Why
Previously
InstallBackendextracted the artifact directly into the target directory with no pre-clean (it only cleaned up on a failed download). Because each backend artifact is a full image, not a diff layer, extraction overwrote same-named files but left behind any file from a previous version that no longer exists in the new artifact. For a heavy backend like vLLM, that means a stale.soor an orphaned package dir from an old version can linger next to the freshly pulled one and shadow it at import time — surfacing as confusing load failures.After this change, install and upgrade leave identical on-disk state: a reinstall fully replaces the backend (including its prebuilt
venv/) rather than overlaying onto it. This makeslocal-ai backends installa reliable recovery path for a stale/mismatched backend once a rebuilt artifact is available.Testing
core/gallerysuite passes (incl. the real install-from-gallery test that exercises the swap on an actual OCI extraction).golangci-lintclean (new-from-merge-base).Scope note
This addresses the recovery half of #10720 (making reinstall a real clean replace). The issue's other asks — surfacing the backend subprocess stderr on load failure, and a WARN on LocalAI-version/backend mismatch — were intentionally descoped here and remain open as follow-ups.
Part of #10720
🤖 Generated with Claude Code