Skip to content

Install an Endpoint with no local catalog - #215

Merged
rbardaji merged 6 commits into
mainfrom
feature/214-install-without-catalog
Aug 3, 2026
Merged

Install an Endpoint with no local catalog#215
rbardaji merged 6 commits into
mainfrom
feature/214-install-without-catalog

Conversation

@rbardaji

@rbardaji rbardaji commented Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Closes #214.

The lightest Endpoint there is — nothing installed, nothing stored locally, every optional integration off — could not be chosen. The installer's local-catalog question had four answers and all four configured a catalog, and no combination of environment variables produced a working Endpoint without one.

What this adds

LOCAL_CATALOG_BACKEND=none is now a deployment that stores nothing locally: no MongoDB, no CKAN. It authenticates users, searches the platform's global catalog, serves its UI and reports to the Federation.

The installer offers it as the first answer and as the default for --backend:

  Which local catalog should this Endpoint use?
    1) None — nothing is stored locally (quickest)
    2) MongoDB, installed alongside the Endpoint
    3) MongoDB, one I already have
    4) CKAN, installed by this script (takes several minutes)
    5) CKAN, one I already have
  Choice [1]:

It renders LOCAL_CATALOG_BACKEND=none with CKAN_LOCAL_ENABLED=False and blanks CKAN_URL, CKAN_API_KEY and MONGODB_CONNECTION_STRING, so nothing is left pointing at a service that was not installed. Running the installer again with --backend mongodb or --backend ckan adds a catalog later.

Why the API needed changing too

Switching the local catalog off was not enough on its own:

  • The readiness probe reported the catalog as disabled only for the CKAN backend. With any other backend it probed the catalog even though CKAN_LOCAL_ENABLED=False had already unmounted the local catalog routes and made /search?server=local answer 400 — so an Endpoint configured deliberately without a usable catalog answered HTTP 503 and looked broken to any orchestrator.
  • Catalog statistics are collected inside the same try as the rest of the metrics payload. Asking for a repository that does not exist left the payload empty and skipped the POST, so the Endpoint would have stopped reporting to the Federation altogether rather than reporting without dataset counts.
  • The routes that write to a local catalog were mounted on the master switch alone, without asking whether a backend provided one.

Verified

  • Full suite in the built image: 1199 passed. Installer render tests: 16 passed. black --check . and flake8 clean.
  • A real no-catalog install: the installer rendered the configuration, the Endpoint came up, /health and /ready answered 200 with local_catalog: {status: disabled, backend: none}, the UI served, /search?server=global answered 200, /search?server=local answered 400 with "Local CKAN is disabled and cannot be used", the registration/update/delete/resource routes were absent from the OpenAPI schema, and metrics posted to the Federation successfully.

Backwards compatibility

ckan and mongodb behave exactly as before. Two changes affect existing setups:

  • A deployment running with CKAN_LOCAL_ENABLED=False and a MongoDB backend was answering 503 on /ready and now answers 200 with the catalog reported disabled.
  • Unattended installer runs that did not pass --backend used to get MongoDB and now get no catalog; add --backend mongodb to keep the previous result.

Raul Bardaji added 6 commits August 3, 2026 14:16
LOCAL_CATALOG_BACKEND=none is a deployment that stores nothing locally: no
MongoDB, no CKAN. It authenticates users, searches the global catalog and
reports to the Federation, which is what most Endpoints are asked to do, and
it needs nothing installed.

Until now the setting only accepted 'ckan' or 'mongodb', so there was no way
to say it. Turning the local catalog off with CKAN_LOCAL_ENABLED=False and
leaving a backend named did not work either: the readiness probe kept
checking the backend for every value except 'ckan', reported it down and
answered 503 for a deployment running exactly as configured.

- catalog_settings gains has_local_catalog, and asking for a repository
  without one now explains that rather than reporting an unsupported backend.
- /ready reports the local catalog as disabled whenever it cannot be reached
  through the API — with no backend, or with the master switch off on any
  backend, since that unmounts the routes and rejects server=local.
- /status reports the backend disconnected without attempting a connection.
- The metrics task no longer asks for a repository it does not have. Catalog
  counts share a try/except with the whole payload, so the exception left the
  payload empty and skipped the POST: an Endpoint with no catalog would have
  silently stopped reporting to the Federation.
- The routes that write to a local catalog are only mounted when a backend
  provides one.
…o it

The lightest Endpoint there is: nothing installed, nothing stored locally,
every optional integration off. It was not on offer — the local catalog
question had four answers and all four configured a catalog, so a MongoDB was
started even when nothing would ever be written to it.

It is now the first choice at the prompt and the default for --backend, since
it is the quickest Endpoint to stand up and a catalog can be added later by
running the installer again. It renders LOCAL_CATALOG_BACKEND=none with
CKAN_LOCAL_ENABLED=False, and blanks the CKAN and MongoDB settings so nothing
points at a service that was not installed.
A new docs/sequence-diagrams/ folder, one process per file, with the first
one: installing an Endpoint with no Federation registration and no local
catalog, every answer left at its default. It follows the run from the first
prompt to the Endpoint answering /health, and shows the .env it produces —
including two defaults worth knowing, IS_PUBLIC=True (an Endpoint that never
registered still reports metrics) and the development TEST_TOKEN.
mcp 2.0.0 changed the signature of its low-level Server, which fastapi-mcp
0.4.0 still calls positionally. FastApiMCP(app) runs at import time, so an
unconstrained resolution produced a container that does not start, and CI
failed on every branch. Existing images were unaffected: their dependencies
were resolved when they were built.
@rbardaji

rbardaji commented Aug 3, 2026

Copy link
Copy Markdown
Collaborator Author

Also closes #216: CI was failing on every branch, this one included, because mcp 2.0.0 broke fastapi-mcp 0.4.0 and FastApiMCP(app) runs at import time — a container built today did not start at all. Pinned to mcp<2.0.0, which is a prerequisite for releasing this at all, since the release image is built fresh.

@rbardaji
rbardaji merged commit 0943e36 into main Aug 3, 2026
1 check passed
@rbardaji
rbardaji deleted the feature/214-install-without-catalog branch August 3, 2026 20:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Installing an Endpoint with no local catalog is not possible

1 participant