Skip to content

Commit 8845cce

Browse files
localai-botmudler
andauthored
feat(gallery): default to index.localai.io with GitHub as a mirror (#11409)
The primary is a caching mirror of the same two files, so an install resolves its gallery from infrastructure the project controls. The GitHub URI stays as a mirror, so behaviour is unchanged whenever the primary is unreachable. Docs and agent guides that either state the shipped defaults or hand out a copy-pasteable gallery list are updated to match, so following them no longer silently demotes an install off the new primary. Assisted-by: Claude:claude-opus-5 [go vet] [go test] [golangci-lint] Co-authored-by: Ettore Di Giacinto <mudler@localai.io>
1 parent 07dfb32 commit 8845cce

7 files changed

Lines changed: 102 additions & 10 deletions

File tree

.agents/backend-signing.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,9 @@ entry (`backend/index.yaml`):
6767

6868
```yaml
6969
- name: localai
70-
url: github:mudler/LocalAI/backend/index.yaml@master
70+
url: https://index.localai.io/backends
71+
mirrors:
72+
- github:mudler/LocalAI/backend/index.yaml@master
7173
verification:
7274
issuer: "https://token.actions.githubusercontent.com"
7375
identity_regex: "^https://github\\.com/mudler/LocalAI/\\.github/workflows/backend_merge\\.yml@refs/(heads/master|tags/.+)$"

.agents/ci-caching.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,7 @@ Two properties this relies on:
198198

199199
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.
200200

201-
`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.
201+
`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.
202202

203203
Two properties to preserve if you touch it:
204204

core/config/runtime_settings_startup.go

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,13 @@ import (
1212
// the "${galleries}" / "${backends}" vars, and DefaultRuntimeBaseline uses
1313
// them to tell "kong default" apart from "user-configured" at settings-load
1414
// time - they must stay the single source for both.
15-
const DefaultGalleriesJSON = `[{"name":"localai", "url":"github:mudler/LocalAI/gallery/index.yaml@master"}]`
16-
const DefaultBackendGalleriesJSON = `[{"name":"localai", "url":"github:mudler/LocalAI/backend/index.yaml@master"}]`
15+
//
16+
// The primary is served by index-server (github.com/localai-org/index-server),
17+
// a caching mirror of the files below. The GitHub URI stays as a mirror so an
18+
// install still resolves its gallery unchanged whenever the primary is
19+
// unreachable - see the fallback chain in core/gallery/gallery_mirrors.go.
20+
const DefaultGalleriesJSON = `[{"name":"localai", "url":"https://index.localai.io/models", "mirrors":["github:mudler/LocalAI/gallery/index.yaml@master"]}]`
21+
const DefaultBackendGalleriesJSON = `[{"name":"localai", "url":"https://index.localai.io/backends", "mirrors":["github:mudler/LocalAI/backend/index.yaml@master"]}]`
1722

1823
func mustGalleries(jsonList string) []Gallery {
1924
var g []Gallery
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
package config_test
2+
3+
import (
4+
"encoding/json"
5+
6+
"github.com/mudler/LocalAI/core/config"
7+
8+
. "github.com/onsi/ginkgo/v2"
9+
. "github.com/onsi/gomega"
10+
)
11+
12+
var _ = Describe("default galleries", func() {
13+
It("serves the model gallery from index.localai.io with GitHub as a mirror", func() {
14+
var galleries []config.Gallery
15+
Expect(json.Unmarshal([]byte(config.DefaultGalleriesJSON), &galleries)).To(Succeed())
16+
Expect(galleries).To(HaveLen(1))
17+
Expect(galleries[0].Name).To(Equal("localai"))
18+
Expect(galleries[0].URL).To(Equal("https://index.localai.io/models"))
19+
Expect(galleries[0].Mirrors).To(Equal([]string{"github:mudler/LocalAI/gallery/index.yaml@master"}))
20+
})
21+
22+
It("serves the backend gallery from index.localai.io with GitHub as a mirror", func() {
23+
var galleries []config.Gallery
24+
Expect(json.Unmarshal([]byte(config.DefaultBackendGalleriesJSON), &galleries)).To(Succeed())
25+
Expect(galleries).To(HaveLen(1))
26+
Expect(galleries[0].Name).To(Equal("localai"))
27+
Expect(galleries[0].URL).To(Equal("https://index.localai.io/backends"))
28+
Expect(galleries[0].Mirrors).To(Equal([]string{"github:mudler/LocalAI/backend/index.yaml@master"}))
29+
})
30+
31+
// The mirror is the whole reason this default is safe to ship: if
32+
// index.localai.io is unreachable, an install must still resolve its
33+
// gallery from GitHub exactly as it did before.
34+
It("always leaves a reachable fallback behind the primary", func() {
35+
for _, raw := range []string{config.DefaultGalleriesJSON, config.DefaultBackendGalleriesJSON} {
36+
var galleries []config.Gallery
37+
Expect(json.Unmarshal([]byte(raw), &galleries)).To(Succeed())
38+
for _, g := range galleries {
39+
Expect(g.Mirrors).ToNot(BeEmpty(), "default %q has no mirror", g.Name)
40+
}
41+
}
42+
})
43+
44+
// mustGalleries panics on malformed JSON, and these constants are also
45+
// fed to kong as defaults, so a typo would be a startup crash rather
46+
// than a config error.
47+
It("parses through the same path startup uses", func() {
48+
baseline := config.DefaultRuntimeBaseline()
49+
Expect(baseline.Galleries).To(HaveLen(1))
50+
Expect(baseline.BackendGalleries).To(HaveLen(1))
51+
Expect(baseline.Galleries[0].URL).To(Equal("https://index.localai.io/models"))
52+
Expect(baseline.BackendGalleries[0].URL).To(Equal("https://index.localai.io/backends"))
53+
})
54+
55+
// The baseline decides "kong default" vs "user-configured", and since
56+
// the defaults grew a Mirrors slice that comparison runs through
57+
// GalleriesEqual rather than ==. A default install must still let the
58+
// persisted file apply, and any override - including one that differs
59+
// from the default only by its mirrors - must still be seen as env-set.
60+
Context("as the option-less startup baseline", func() {
61+
It("treats an untouched default list as not env-set, so the file applies", func() {
62+
o := config.DefaultRuntimeBaseline()
63+
saved := []config.Gallery{{Name: "mine", URL: "https://example.com/index.yaml"}}
64+
savedBackends := []config.Gallery{{Name: "mine-backends", URL: "https://example.com/backends.yaml"}}
65+
o.ApplyRuntimeSettingsAtStartup(&config.RuntimeSettings{
66+
Galleries: &saved,
67+
BackendGalleries: &savedBackends,
68+
})
69+
Expect(o.Galleries).To(Equal(saved))
70+
Expect(o.BackendGalleries).To(Equal(savedBackends))
71+
})
72+
73+
It("treats LOCALAI_GALLERIES as env-set even when it only drops the mirror", func() {
74+
o := config.DefaultRuntimeBaseline()
75+
// Same primary as the default, mirror removed: env-set.
76+
o.Galleries = []config.Gallery{{Name: "localai", URL: "https://index.localai.io/models"}}
77+
saved := []config.Gallery{{Name: "file", URL: "https://file.example/index.yaml"}}
78+
o.ApplyRuntimeSettingsAtStartup(&config.RuntimeSettings{Galleries: &saved})
79+
Expect(o.Galleries[0].Name).To(Equal("localai"),
80+
"an env list differing only by mirrors must still win over the file")
81+
})
82+
})
83+
})

docs/content/features/backends.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ they provide. Add a `verification` policy to the gallery configuration, then
7979
enable strict integrity mode:
8080

8181
```bash
82-
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/.+)$"}}]'
82+
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/.+)$"}}]'
8383
export LOCALAI_REQUIRE_BACKEND_INTEGRITY=1
8484
local-ai run
8585
```

docs/content/features/model-gallery.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,13 +100,13 @@ To use additional repositories you need to start `local-ai` with the `GALLERIES`
100100
GALLERIES=[{"name":"<GALLERY_NAME>", "url":"<GALLERY_URL"}]
101101
```
102102

103-
For example, to enable the default `localai` repository, you can start `local-ai` with:
103+
For example, to spell out the default `localai` repository, you can start `local-ai` with:
104104

105105
```
106-
GALLERIES=[{"name":"localai", "url":"github:mudler/localai/gallery/index.yaml"}]
106+
GALLERIES=[{"name":"localai", "url":"https://index.localai.io/models", "mirrors":["github:mudler/LocalAI/gallery/index.yaml@master"]}]
107107
```
108108

109-
where `github:mudler/localai/gallery/index.yaml` will be expanded automatically to `https://raw.githubusercontent.com/mudler/LocalAI/main/index.yaml`.
109+
`https://index.localai.io/models` is a caching mirror of the same index file, and the `github:` entry is the fallback used whenever it cannot be reached. `github:mudler/LocalAI/gallery/index.yaml@master` is expanded automatically to `https://raw.githubusercontent.com/mudler/LocalAI/master/gallery/index.yaml`.
110110

111111
Note: the url are expanded automatically for `github` and `huggingface`, however `https://` and `http://` prefix works as well.
112112

docs/content/features/runtime-settings.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -148,13 +148,15 @@ The `runtime_settings.json` file follows this structure:
148148
"federated": false,
149149
"galleries": [
150150
{
151-
"url": "github:mudler/LocalAI/gallery/index.yaml@master",
151+
"url": "https://index.localai.io/models",
152+
"mirrors": ["github:mudler/LocalAI/gallery/index.yaml@master"],
152153
"name": "localai"
153154
}
154155
],
155156
"backend_galleries": [
156157
{
157-
"url": "github:mudler/LocalAI/backend/index.yaml@master",
158+
"url": "https://index.localai.io/backends",
159+
"mirrors": ["github:mudler/LocalAI/backend/index.yaml@master"],
158160
"name": "localai"
159161
}
160162
],

0 commit comments

Comments
 (0)