Metadata-Version: 2.4
Name: dbnomics-docker
Version: 0.1.1.dev1
Summary: CLI to run a local DBnomics stack for testing fetcher output
Author: Christophe Benz
Author-email: Christophe Benz <christophe.benz@nomics.world>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE.md
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Project-URL: Homepage, https://git.nomics.world/dbnomics/dbnomics-docker
Project-URL: Bug Tracker, https://git.nomics.world/dbnomics/dbnomics-docker/-/issues
Description-Content-Type: text/markdown

# DBnomics Docker

Run a local DBnomics stack to test fetcher output. One command from your
fetcher directory:

```bash
uvx dbnomics-docker up
```

## Installation

This project requires [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) to be installed on your machine.

[Podman](https://podman.io/) is also supported (cf section below).

It is recommended to install [uv](https://docs.astral.sh/uv/) to run the commands with [uvx](https://docs.astral.sh/uv/guides/tools/).

## Quick start

```bash
# In your fetcher directory, after producing converted-data/:
cd abc-fetcher
uv run convert.py source-data converted-data  # produces converted-data/
uvx dbnomics-docker up                        # starts stack + indexes your data
```

Services will be available at:

- **Website**: <http://localhost:3000/{slug}>
- **API**: <http://localhost:5000/providers/{slug}>
- **Solr**: <http://localhost:8983>

## How it works

`uvx dbnomics-docker up` does the following:

1. Creates a `./dbnomics-docker/` project directory with the compose files and
   Solr configuration
2. Generates a `compose.override.yml` that mounts your fetcher's
   `converted-data/` directory as `/converted-data/{slug}-json-data` inside the
   API container
3. Starts the Docker Compose stack (`docker compose up -d --remove-orphans`)
4. Waits for Solr to be ready
5. Indexes your provider's data into Solr

You can inspect the project directory at `./dbnomics-docker/` and use
`docker compose` commands directly from it.

## Commands

```bash
uvx dbnomics-docker create   # create the ./dbnomics-docker/ project (up does it automatically)
uvx dbnomics-docker up       # start stack + index converted-data/
uvx dbnomics-docker down     # stop the stack (keeps the project directory)
uvx dbnomics-docker delete   # stop + delete the project directory
uvx dbnomics-docker index    # re-index after data changes
uvx dbnomics-docker ps [-a]  # list containers
uvx dbnomics-docker logs [-f api]  # show logs
```

## Using Podman

```bash
export COMPOSE_CMD=podman-compose
uvx dbnomics-docker up
```

## Troubleshooting

- **Ports already in use** — if `:3000`, `:5000` or `:8983` are taken, stop
  the conflicting process or the previous stack with `uvx dbnomics-docker down`.
- **Provider not found** — the `converted-data/` directory must exist with
  your fetcher's output before running `up`.
