Run DBnomics locally

This chapter explains why and how to run a full DBnomics stack locally with Docker Compose, using the dbnomics-docker CLI.

Why run DBnomics locally?

After writing a fetcher, you need to verify that the converted data is correctly visible in the DBnomics web interface. Running a local stack lets you:

• visualize data as users will see it — you can browse the provider page, explore dataset dimensions, and inspect series just like on the production site

• detect problems more easily — missing dimensions, incorrect labels, broken hierarchies become obvious when you navigate the actual UI

• iterate faster — fix an issue in the fetcher, re-run the conversion, re-index, and reload the page: a tight trial-error-correction loop without waiting for a remote deployment

• leverage dimension filtering — the dataset page’s left sidebar lets you filter series dynamically by dimension value. This is invaluable for validating high-dimensional datasets, and impossible to do by inspecting raw converted files alone

Other use cases (developing dbnomics-api or dbnomics-website itself) are also possible but outside the scope of this tutorial.

What services are included?

The Docker Compose stack orchestrated by dbnomics-docker runs three services:

Service	Role	Local access
Solr	Search and indexing engine	http://localhost:8983
dbnomics-api	REST API (JSON/CSV/TSV)	http://localhost:5000 (apidocs: http://localhost:5000/apidocs)
dbnomics-website	Web user interface	http://localhost:3000

Note

The stack does not include fetcher execution pipelines. Fetchers run separately (in GitLab CI or locally with uv run). The stack only ingests the converted files produced by fetchers.

Prerequisites

• A Linux machine with Docker installed.

• Docker Compose (docker compose command).

Quick start

From your fetcher directory, after running the conversion:

cd abc-fetcher
uv run convert.py source-data converted-data  # produces converted-data/
uvx dbnomics-docker up                        # starts the stack and indexes your data

The first launch takes longer because Docker downloads the images.

Once started, your provider is available at:

• Website: http://localhost:3000/ABC

• API: http://localhost:5000/providers/ABC

Commands

uvx dbnomics-docker up       # create project (if needed), start stack, index data
uvx dbnomics-docker down     # stop the stack (keeps the project directory)
uvx dbnomics-docker index    # re-index after data changes (stack must be running)
uvx dbnomics-docker ps [-a]  # list containers
uvx dbnomics-docker logs [-f api]  # show logs
uvx dbnomics-docker delete   # stop and remove the project directory

The provider slug is auto-detected from the current directory name (e.g., abc-fetcher → abc). Override it with --provider-slug.

For details about how the CLI works, see the dbnomics-docker README.

Troubleshooting

Check the logs:

uvx dbnomics-docker logs -f

Common issues:

• Ports already in use — if :3000, :5000 or :8983 are taken, stop the conflicting process or run uvx dbnomics-docker down.

• Provider does not appear on the site — verify that the converted-data/ directory exists with the right structure and run uvx dbnomics-docker index.