# Run DBnomics locally

This chapter explains why and how to run a full DBnomics stack locally with
Docker Compose, using the
[dbnomics-docker](https://git.nomics.world/dbnomics/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](https://docs.docker.com/install/) installed.
- [Docker Compose](https://docs.docker.com/compose/install/) (`docker
  compose` command).

## Quick start

From your fetcher directory, after running the conversion:

```bash
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

```bash
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](https://git.nomics.world/dbnomics/dbnomics-docker) README.

## Troubleshooting

Check the logs:

```bash
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`.