diff --git a/samples/Bunny/bunny-demo.compose.yml b/samples/Bunny/bunny-demo.compose.yml new file mode 100644 index 0000000..7d148cf --- /dev/null +++ b/samples/Bunny/bunny-demo.compose.yml @@ -0,0 +1,34 @@ +name: bunny-demo + +services: + db: + image: postgres:16 + ports: + - 5432:5432 + environment: + POSTGRES_PASSWORD: postgres + POSTGRES_DB: omop + + omop-lite: + image: ghcr.io/health-informatics-uon/omop-lite + depends_on: + - db + environment: + DB_PASSWORD: postgres + DB_NAME: omop + SYNTHETIC: true + + bunny: + image: ghcr.io/health-informatics-uon/hutch/bunny:edge + environment: + DATASOURCE_DB_USERNAME: postgres + DATASOURCE_DB_PASSWORD: postgres + DATASOURCE_DB_DATABASE: omop + DATASOURCE_DB_DRIVERNAME: postgresql + DATASOURCE_DB_SCHEMA: omop + DATASOURCE_DB_PORT: 5432 + DATASOURCE_DB_HOST: db + BUNNY_LOGGER_LEVEL: DEBUG + depends_on: + omop-lite: + condition: service_completed_successfully diff --git a/website/pages/bunny/quickstart.mdx b/website/pages/bunny/quickstart.mdx index 78c56aa..f10e879 100644 --- a/website/pages/bunny/quickstart.mdx +++ b/website/pages/bunny/quickstart.mdx @@ -1,36 +1,40 @@ import { Steps } from "nextra/components"; +import { Callout } from "nextra/components"; # Quickstart -The quickest way to run Bunny is to use the provided [Bunny Image](https://github.com/Health-Informatics-UoN/hutch-bunny/pkgs/container/hutch%2Fbunny) command line interface to run a query against your existing OMOP database. This way you don't need an upstream Task API to connect to yet. +The easiest way to run Bunny is by using the provided [Bunny Image](https://github.com/Health-Informatics-UoN/hutch-bunny/pkgs/container/hutch%2Fbunny) command line interface to query an OMOP CDM database, without needing an upstream Task API. + +This guide will help you quickly set up a local OMOP CDM database and run a query against it. ## Prerequisites -- A [OMOP CDM](developers/omop_cdm) database - Docker -## Setup +## Run a query -### Configuration -You'll need to set some environment variables to connect the container to the database, you can create a `.env` file with your database details: - -```bash copy filename=".env" -DATASOURCE_DB_USERNAME=postgres -DATASOURCE_DB_PASSWORD=postgres -DATASOURCE_DB_DATABASE=postgres -DATASOURCE_DB_DRIVERNAME=postgresql -DATASOURCE_DB_SCHEMA=public -DATASOURCE_DB_PORT=5432 -DATASOURCE_DB_HOST=localhost +### Get the Demo Compose file + +Download the [sample Bunny Demo Compose](https://raw.githubusercontent.com/Health-Informatics-UoN/hutch/refs/heads/main/samples/Bunny/bunny-demo.compose.yml) file by running the command: + +```bash copy +curl -O https://raw.githubusercontent.com/Health-Informatics-UoN/hutch/refs/heads/main/samples/Bunny/bunny-demo.compose.yml ``` -See [configuration](config) for further details. +Or manually saving it to a file `bunny-demo.compose.yml` +### Run the Compose file -### Sample query file +This will start the database, initialise it with a synthetic OMOP CDM dataset, and run a query against it. -For ease, the sample query is a .json file: +```bash copy +docker compose -f bunny-demo.compose.yml run --entrypoint uv bunny run bunny --body tests/queries/availability.json +``` + +This will take a minute or so to download the images and start the containers. + +The query file is a JSON file that contains the query to run, which is a simple cohort definition, querying the `Person` table for `8507`. ```json copy filename="availability.json" { @@ -61,34 +65,42 @@ For ease, the sample query is a .json file: } ``` -## Run a query +Congratulations on your first Bunny query! -You can run the query command directly against the Container, by mounting its volume and passing the arguments. +### View the results -```bash copy -docker run \ - -v $(pwd)/availability.json:/availability.json \ - -v $(pwd)/output.json:/output.json \ - --env-file .env \ - --entrypoint uv \ - ghcr.io/health-informatics-uon/hutch/bunny:edge \ - run bunny --body /availability.json +You should see output like the following: + +```json +{ + "status": "ok", + "protocolVersion": "v2", + "uuid": "unique_id", + "queryResult": { + "count": 44, + "datasetCount": 0, + "files": [] + }, + "message": "", + "collection_id": "collection_id" +} ``` -If you're running your OMOP CDM database in Docker, then you'll need to add the Bunny container to the same network to access it. You can do this by adding the `network` argument to the run command. +That contains the **results** of the query, which was 44. + +### Clean up ```bash copy -docker run \ - --network omop-cdm \ - -v $(pwd)/availability.json:/availability.json \ - -v $(pwd)/output.json:/output.json \ - --env-file .env \ - --entrypoint uv \ - ghcr.io/health-informatics-uon/hutch/bunny:edge \ - run bunny --body /availability.json +docker compose -f bunny-demo.compose.yml down ``` -Your results should be available in `output.json` +This will stop the database and remove the containers. + +To remove the images, run: + +```bash copy +docker rmi -f ghcr.io/health-informatics-uon/omop-lite:latest ghcr.io/health-informatics-uon/hutch/bunny:edge +``` diff --git a/website/pages/index.mdx b/website/pages/index.mdx index 0c61cbc..928263b 100644 --- a/website/pages/index.mdx +++ b/website/pages/index.mdx @@ -1,7 +1,13 @@ +import { Cards } from 'nextra/components' +import { Rabbit, Repeat, Lock } from "lucide-react"; + ![](/images/hutch-logo-colour.svg) -# Welcome to Hutch -Hutch provides tools for federated activities in secure environments. +### Hutch provides tools for federated activities in secure environments. -You can find the documentation for the Hutch implementation of the Executing Agent module of the TRE-FX stack at [Hutch TRE-FX](https://health-informatics-uon.github.io/hutch-trefx/). + + } href="/bunny" /> + } href="/relay"/> + } href="https://health-informatics-uon.github.io/hutch-trefx/"/> +