feat: self-hosted STAC Browser at /stac-browser/

[turban]

Background

The STAC catalog at /stac/catalog.json has no browser-friendly HTML interface. Linking to the externally hosted STAC Browser at radiantearth.github.io is not viable because Climate API instances may run on private networks with no public internet access.

Goal

Serve the STAC Browser SPA at /stac-browser/ as self-hosted static assets, pre-configured to open the local catalog automatically. Works on air-gapped and intranet deployments with no external dependencies at runtime.

Implementation

1. Build the STAC Browser SPA

The STAC Browser is a Vue.js application. Build it once with the catalog URL baked in:

git clone https://github.com/radiantearth/stac-browser
cd stac-browser
npm install
STAC_BROWSER_PATH=/stac-browser \
  catalogUrl=/stac/catalog.json \
  npm run build

The build output is a self-contained directory of HTML, JS, and CSS assets (~3–5 MB).

2. Bundle the built assets as package data

Commit the built assets under src/climate_api/data/stac_browser/ so they ship inside the wheel and are available in pip-installed deployments without a separate build step. Add a note in the contributing docs explaining how to rebuild when upgrading STAC Browser.

3. Serve via FastAPI StaticFiles

Mount the directory in main.py:

from fastapi.staticfiles import StaticFiles
import importlib.resources

stac_browser_path = importlib.resources.files("climate_api") / "data" / "stac_browser"
_app.mount("/stac-browser", StaticFiles(directory=str(stac_browser_path), html=True))

4. Link from the landing page

Add a "STAC Browser" entry to the Explore section of the HTML landing page (issue #68) pointing to /stac-browser/.

Notes

• The built assets are static files with no server-side logic — no additional Python dependencies required.
• STAC Browser built with a relative catalogUrl will always point to the co-located catalog regardless of the public hostname, so the same image works behind any reverse proxy.
• The build step only needs to be repeated when upgrading the STAC Browser version. Pin the version in the contributing docs.
• StaticFiles is already available via Starlette (a current dependency).