Catalog sources

The Catalog page lists ready-made service templates. They come from sources: the catalog bundled with Fadebox, and any git repositories you register beside it. A source of your own is how a team publishes its own building blocks — an internal catalog everyone imports from, kept in git and reviewed like any other repository.

Registering a source only makes its entries browsable. Importing one still copies it into an ordinary template, exactly as importing a bundled entry does, so a catalog that changes, breaks or disappears can never reach a template or a running instance.

Register a source

Catalog → Add source, as an administrator (global role admin or template_admin). A source that belongs to one project is registered from that project's catalog page by its maintainers — see Sources for one project.

Field	Meaning
Name	Label shown on the page. Optional — the slug stands in when it is empty.
Slug	Identifier for the source, e.g. acme, filled in from the name and yours to change. Recorded on every template imported from it.
Repository URL	https:// clone URL. Only https is allowed.
Branch or tag	What the catalog is read from. Defaults to main.
Subdirectory	Where index.yaml lives, if not at the repository root.
Access token	Optional token for a private repository. Write-only — accepted, never returned.

Saving fetches the repository straight away, so a wrong URL, ref or token is reported before you walk away. A source whose first fetch fails is kept with the reason on it: fix the field and save again.

Over MCP, create_catalog_source registers a repository and sync_catalog_source re-reads it after a push, answering with the index's format error when there is one; get_catalog_source, update_catalog_source, set_catalog_source_enabled and delete_catalog_source are the rest of the lifecycle. Each takes an optional project for a project's own source — see Authoring templates with an agent.

The official catalog

The catalog bundled with Fadebox is also published as a git source:

Field	Value
Slug	official
Repository URL	https://github.com/fadebox-io/catalog.git
Branch or tag	master

Registering it is optional. Your installation already carries that same catalog inside the application — which is why a fresh install has a populated Catalog page with no network access at all — packaged from one commit of this repository, so the entries a build serves are the ones it was released with. The Sources list shows which commit that is, in the same column a registered source shows its last sync.

Register the repository when you would rather have entries as they are published than as each release ships them.

Doing so lists every entry twice, once from each source. If you would rather see each entry once, switch the bundled catalog off.

It is Apache-2.0, so it also serves as the worked example for a catalog of your own: fork it, keep the layout, replace the entries.

Sync is explicit

Fadebox serves a source from the snapshot it took at the last sync, and reads that snapshot from a local clone. Browsing the catalog never touches the network, a restart needs no repository to be reachable, and pushing to the catalog changes nothing anyone sees until someone presses Sync.

The row for each source shows the commit it is serving and when. A sync that fails — the remote is unreachable, the token expired, index.yaml no longer parses — says so on the source and keeps serving the previous snapshot.

Point a source at a tag rather than a branch to pin it: syncing then picks up nothing until you move the tag or change the field.

Switching a catalog off

Each source has a switch. A source that is off keeps everything — its URL, its branch, its stored token, the snapshot it last fetched — and serves none of it: its entries disappear from the catalog, cannot be imported, and stop reporting updates for templates already copied from them. It stays in the list, which is where you switch it back on.

That is different from a source whose sync failed: one is not being asked, the other tried and could not. And it is different from removing it, which throws the registration away.

The catalog bundled with fadebox can be switched off too. It is on by default — a fresh install has a populated Catalog page with no network access at all — but an installation that runs on a catalog of its own does not have to list fadebox's entries beside it. Templates already imported from it keep working; they simply stop reporting updates while it is off.

Switching a global source on or off is an administrator's action; a project's own source is its maintainers'. Either way it is recorded in the audit log.

The catalog format

A catalog is a directory in a git repository: an index, and one directory per entry.

index.yaml
postgres/
  template.yaml

# index.yaml
apiVersion: fadebox.catalog/v1
name: Acme platform catalog
entries:
  - slug: postgres            # stable: templates record it as provenance
    name: PostgreSQL
    version: 1.2.0
    description: Single-node PostgreSQL with healthcheck and persistent storage.
    tags: [ database ]
    path: postgres/template.yaml

# postgres/template.yaml
slug: postgres
name: PostgreSQL
version: 1.2.0
description: Single-node PostgreSQL with healthcheck and persistent storage.
spec: |                       # exactly what the template editor accepts
  services:
    db:
      image: postgres:18
      environment:
        POSTGRES_PASSWORD: postgres
files:                        # optional, injected into the container at deploy
  - serviceKey: db
    targetPath: /docker-entrypoint-initdb.d/init.sql
    content: |
      create extension if not exists pgcrypto;

The payload is a template as Fadebox already understands it — see Template authoring for what spec may contain.

Two rules make the update hint work:

• An entry's slug is stable. Templates imported from an entry record it; renaming the entry orphans them, and they stop reporting updates.
• version in index.yaml is the update signal. A new commit with an unchanged version is not an update. Bump the version when you want existing copies to notice.

Finding things in a large catalog

The search box above the grid searches every entry of every source you can see — names, ids, descriptions, tags and source names — and the grid loads more as you scroll rather than fetching whole catalogs at once. So a source carrying hundreds of entries costs you a search box, not a slower page. The source dropdown narrows the same way.

Importing, and staying up to date

Importing works the same for every source: the entry becomes an editable template, globally or in one project, under a name and slug you choose. The copy records the source, the entry and the version it came from.

When a later sync brings a newer version of that entry, the copy's row on the Templates page shows an update hint, and Update from catalog re-imports it in place — spec, files and description follow the catalog, name and slug stay yours. Nothing updates on its own.

Pulling the entry's images from your own registry

Catalog entries name public images — postgres:18-alpine, redis:7-alpine — because that is what makes them portable between installations. On a host that cannot reach Docker Hub, or one being rate-limited by it, that means hand-editing every template you import, once per import, forever.

If the installation has a system image registry configured, the import dialog offers Pull Docker Hub images from <registry>, off by default, and lists exactly what it would rewrite before you accept:

Entry names	Imported as
postgres:18-alpine	registry.corp:5000/library/postgres:18-alpine
axllent/mailpit:v1.21	registry.corp:5000/axllent/mailpit:v1.21
quay.io/keycloak/keycloak:26.7	unchanged — not a Docker Hub image

Only Hub references are touched, and the implicit library/ namespace is made explicit, because that is the path a pull-through proxy serves — a Harbor proxy project, an Artifactory remote, registry:2 in proxy mode. Your registry must already proxy or hold the images; Fadebox never pushes to it. Tags and digests ride along untouched.

The choice is remembered on the template, so Update from catalog re-applies it rather than quietly reverting to Docker Hub the first time the entry moves on. The registry itself is resolved each time, so changing the installation's mirror re-points every template that opted in, at its next update.

The checkbox appears only when there is a registry configured and the entry names something it would change; nothing about an import changes otherwise. It rewrites at import only — a template you are reading always names the image that will be pulled. If you want this for every image on a host, including ones Fadebox never sees, the daemon's own registry-mirrors is still the simpler answer; this exists for the path rewrite that a daemon mirror cannot express.

Removing a source leaves every template imported from it untouched; they simply stop reporting updates.

Sources for one project

A source can belong to a project instead of the whole installation: Project → Catalog → Add source. Its entries appear only in that project's catalog and import only into that project, which is what keeps one team's building blocks out of everyone else's list. The project's catalog also shows the bundled entries and every global source, so a team sees one page with everything it may use.

A project's own sources are the project's to administer: its maintainers register, edit, switch, sync and remove them, with no global role needed (since 1.1.2). A template_admin keeps the same access to every project's sources. The global sources a project browses stay read-only from inside it — they are switched, synced and edited on the global Catalog page, and their rows in a project say administered globally rather than leaving an empty gap where a maintainer's own sources have controls. The bundled catalog is the same: it can be switched off, but the switch is installation-wide and so lives on the global page only. Importing an entry into the project is the maintainers' as well: the copy is a project template, written under the unsafe configuration rule like every project template, and the project page's import dialog lands it there without offering a scope. Importing into the global scope stays with the template roles, on the global Catalog page.

What to trust a source with

An entry carries image references and a Compose document that an administrator will deploy. A source is therefore exactly as trusted as whoever can push to its repository, and registering one is the moment to decide that. Fadebox pulls the images through the runtime's configured registry credentials as usual; the catalog itself never carries images.

A source's access token belongs to the scope it was registered in. Editing the source keeps the stored token unless you replace or clear it, so whoever may edit a project's source — its maintainers — may also point it, token and all, at another https:// repository. That is the same rule the project's git repositories follow, and the audit log records the new URL.

A private catalog on your own git server needs no outbound internet access beyond that server.