diff --git a/.agents/backend-signing.md b/.agents/backend-signing.md index 98c32d3e9..5edec5891 100644 --- a/.agents/backend-signing.md +++ b/.agents/backend-signing.md @@ -67,7 +67,9 @@ entry (`backend/index.yaml`): ```yaml - name: localai - url: github:mudler/LocalAI/backend/index.yaml@master + url: https://index.localai.io/backends + mirrors: + - github:mudler/LocalAI/backend/index.yaml@master verification: issuer: "https://token.actions.githubusercontent.com" identity_regex: "^https://github\\.com/mudler/LocalAI/\\.github/workflows/backend_merge\\.yml@refs/(heads/master|tags/.+)$" diff --git a/.agents/ci-caching.md b/.agents/ci-caching.md index 1aa9c54ac..6742049e6 100644 --- a/.agents/ci-caching.md +++ b/.agents/ci-caching.md @@ -198,7 +198,7 @@ Two properties this relies on: The same reasoning applies to master pushes, and the volume is larger there: on 2026-07-30, **12 of the 23 queued `image.yml` runs** were commits like "add 1 new model to gallery" or a docs fix, each rebuilding all 18 container images. -`image.yml` now has a `changes` job that decides once whether the push can affect any image; the other 11 jobs carry `needs: changes` plus an `if:` on its output. Verified against the shipped `Dockerfile`: the final stage copies only `entrypoint.sh`, `healthcheck.sh` and the `local-ai` binary, there is no `go:embed` of `gallery/` or `docs/`, and the gallery is fetched at runtime from `github:mudler/LocalAI/gallery/index.yaml@master`. A gallery-only commit therefore produces byte-identical images, and the gallery change reaches users through GitHub immediately whether or not an image is rebuilt. +`image.yml` now has a `changes` job that decides once whether the push can affect any image; the other 11 jobs carry `needs: changes` plus an `if:` on its output. Verified against the shipped `Dockerfile`: the final stage copies only `entrypoint.sh`, `healthcheck.sh` and the `local-ai` binary, there is no `go:embed` of `gallery/` or `docs/`, and the gallery is fetched at runtime from `https://index.localai.io/models` (a caching mirror of `gallery/index.yaml` on master, with `github:mudler/LocalAI/gallery/index.yaml@master` as the fallback mirror). A gallery-only commit therefore produces byte-identical images, and the gallery change reaches users over the network immediately whether or not an image is rebuilt. Two properties to preserve if you touch it: diff --git a/core/config/runtime_settings_startup.go b/core/config/runtime_settings_startup.go index 9eda102f6..4a25446da 100644 --- a/core/config/runtime_settings_startup.go +++ b/core/config/runtime_settings_startup.go @@ -12,8 +12,13 @@ import ( // the "${galleries}" / "${backends}" vars, and DefaultRuntimeBaseline uses // them to tell "kong default" apart from "user-configured" at settings-load // time - they must stay the single source for both. -const DefaultGalleriesJSON = `[{"name":"localai", "url":"github:mudler/LocalAI/gallery/index.yaml@master"}]` -const DefaultBackendGalleriesJSON = `[{"name":"localai", "url":"github:mudler/LocalAI/backend/index.yaml@master"}]` +// +// The primary is served by index-server (github.com/localai-org/index-server), +// a caching mirror of the files below. The GitHub URI stays as a mirror so an +// install still resolves its gallery unchanged whenever the primary is +// unreachable - see the fallback chain in core/gallery/gallery_mirrors.go. +const DefaultGalleriesJSON = `[{"name":"localai", "url":"https://index.localai.io/models", "mirrors":["github:mudler/LocalAI/gallery/index.yaml@master"]}]` +const DefaultBackendGalleriesJSON = `[{"name":"localai", "url":"https://index.localai.io/backends", "mirrors":["github:mudler/LocalAI/backend/index.yaml@master"]}]` func mustGalleries(jsonList string) []Gallery { var g []Gallery diff --git a/core/config/runtime_settings_startup_test.go b/core/config/runtime_settings_startup_test.go new file mode 100644 index 000000000..410e457d6 --- /dev/null +++ b/core/config/runtime_settings_startup_test.go @@ -0,0 +1,83 @@ +package config_test + +import ( + "encoding/json" + + "github.com/mudler/LocalAI/core/config" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("default galleries", func() { + It("serves the model gallery from index.localai.io with GitHub as a mirror", func() { + var galleries []config.Gallery + Expect(json.Unmarshal([]byte(config.DefaultGalleriesJSON), &galleries)).To(Succeed()) + Expect(galleries).To(HaveLen(1)) + Expect(galleries[0].Name).To(Equal("localai")) + Expect(galleries[0].URL).To(Equal("https://index.localai.io/models")) + Expect(galleries[0].Mirrors).To(Equal([]string{"github:mudler/LocalAI/gallery/index.yaml@master"})) + }) + + It("serves the backend gallery from index.localai.io with GitHub as a mirror", func() { + var galleries []config.Gallery + Expect(json.Unmarshal([]byte(config.DefaultBackendGalleriesJSON), &galleries)).To(Succeed()) + Expect(galleries).To(HaveLen(1)) + Expect(galleries[0].Name).To(Equal("localai")) + Expect(galleries[0].URL).To(Equal("https://index.localai.io/backends")) + Expect(galleries[0].Mirrors).To(Equal([]string{"github:mudler/LocalAI/backend/index.yaml@master"})) + }) + + // The mirror is the whole reason this default is safe to ship: if + // index.localai.io is unreachable, an install must still resolve its + // gallery from GitHub exactly as it did before. + It("always leaves a reachable fallback behind the primary", func() { + for _, raw := range []string{config.DefaultGalleriesJSON, config.DefaultBackendGalleriesJSON} { + var galleries []config.Gallery + Expect(json.Unmarshal([]byte(raw), &galleries)).To(Succeed()) + for _, g := range galleries { + Expect(g.Mirrors).ToNot(BeEmpty(), "default %q has no mirror", g.Name) + } + } + }) + + // mustGalleries panics on malformed JSON, and these constants are also + // fed to kong as defaults, so a typo would be a startup crash rather + // than a config error. + It("parses through the same path startup uses", func() { + baseline := config.DefaultRuntimeBaseline() + Expect(baseline.Galleries).To(HaveLen(1)) + Expect(baseline.BackendGalleries).To(HaveLen(1)) + Expect(baseline.Galleries[0].URL).To(Equal("https://index.localai.io/models")) + Expect(baseline.BackendGalleries[0].URL).To(Equal("https://index.localai.io/backends")) + }) + + // The baseline decides "kong default" vs "user-configured", and since + // the defaults grew a Mirrors slice that comparison runs through + // GalleriesEqual rather than ==. A default install must still let the + // persisted file apply, and any override - including one that differs + // from the default only by its mirrors - must still be seen as env-set. + Context("as the option-less startup baseline", func() { + It("treats an untouched default list as not env-set, so the file applies", func() { + o := config.DefaultRuntimeBaseline() + saved := []config.Gallery{{Name: "mine", URL: "https://example.com/index.yaml"}} + savedBackends := []config.Gallery{{Name: "mine-backends", URL: "https://example.com/backends.yaml"}} + o.ApplyRuntimeSettingsAtStartup(&config.RuntimeSettings{ + Galleries: &saved, + BackendGalleries: &savedBackends, + }) + Expect(o.Galleries).To(Equal(saved)) + Expect(o.BackendGalleries).To(Equal(savedBackends)) + }) + + It("treats LOCALAI_GALLERIES as env-set even when it only drops the mirror", func() { + o := config.DefaultRuntimeBaseline() + // Same primary as the default, mirror removed: env-set. + o.Galleries = []config.Gallery{{Name: "localai", URL: "https://index.localai.io/models"}} + saved := []config.Gallery{{Name: "file", URL: "https://file.example/index.yaml"}} + o.ApplyRuntimeSettingsAtStartup(&config.RuntimeSettings{Galleries: &saved}) + Expect(o.Galleries[0].Name).To(Equal("localai"), + "an env list differing only by mirrors must still win over the file") + }) + }) +}) diff --git a/docs/content/features/backends.md b/docs/content/features/backends.md index 5eed109d0..ef5627eb6 100644 --- a/docs/content/features/backends.md +++ b/docs/content/features/backends.md @@ -79,7 +79,7 @@ they provide. Add a `verification` policy to the gallery configuration, then enable strict integrity mode: ```bash -export LOCALAI_BACKEND_GALLERIES='[{"name":"localai","url":"github:mudler/LocalAI/backend/index.yaml@master","verification":{"issuer":"https://token.actions.githubusercontent.com","identity_regex":"^https://github\\.com/mudler/LocalAI/\\.github/workflows/backend_merge\\.yml@refs/(heads/master|tags/.+)$"}}]' +export LOCALAI_BACKEND_GALLERIES='[{"name":"localai","url":"https://index.localai.io/backends","mirrors":["github:mudler/LocalAI/backend/index.yaml@master"],"verification":{"issuer":"https://token.actions.githubusercontent.com","identity_regex":"^https://github\\.com/mudler/LocalAI/\\.github/workflows/backend_merge\\.yml@refs/(heads/master|tags/.+)$"}}]' export LOCALAI_REQUIRE_BACKEND_INTEGRITY=1 local-ai run ``` diff --git a/docs/content/features/model-gallery.md b/docs/content/features/model-gallery.md index 24a357d56..e5d3ce656 100644 --- a/docs/content/features/model-gallery.md +++ b/docs/content/features/model-gallery.md @@ -100,13 +100,13 @@ To use additional repositories you need to start `local-ai` with the `GALLERIES` GALLERIES=[{"name":"", "url":"