From 3862d77a25f76f95c9058b64ce693d545317f56b Mon Sep 17 00:00:00 2001 From: Andy Rae Date: Thu, 6 Feb 2025 20:42:11 +0000 Subject: [PATCH 1/5] Add Docker Compose configuration for Bunny demo environment --- samples/Bunny/bunny-demo.compose.yml | 34 ++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 samples/Bunny/bunny-demo.compose.yml 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 From 436255ebdbbd6b122e72a2f621ad517d833fbfb5 Mon Sep 17 00:00:00 2001 From: Andy Rae Date: Thu, 6 Feb 2025 20:59:37 +0000 Subject: [PATCH 2/5] Update Bunny Quickstart Documentation with Simplified Demo Setup --- website/pages/bunny/quickstart.mdx | 76 ++++++++++++++---------------- 1 file changed, 36 insertions(+), 40 deletions(-) diff --git a/website/pages/bunny/quickstart.mdx b/website/pages/bunny/quickstart.mdx index 78c56aa..9b10e2d 100644 --- a/website/pages/bunny/quickstart.mdx +++ b/website/pages/bunny/quickstart.mdx @@ -1,36 +1,38 @@ 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 +This will start the database, initialise it with a synthetic OMOP CDM dataset, and run a query against it. -### Sample query file +```bash copy +docker compose -f bunny-demo.compose.yml run --entrypoint uv bunny run bunny --body tests/queries/availability.json +``` -For ease, the sample query is a .json file: +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 +63,28 @@ For ease, the sample query is a .json file: } ``` -## Run a query - -You can run the query command directly against the Container, by mounting its volume and passing the arguments. +Congratulations on your first Bunny query! -```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 -``` +### View the results -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. +You should see output like the following: -```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 +```json +{ + "status": "ok", + "protocolVersion": "v2", + "uuid": "unique_id", + "queryResult": { + "count": 44, + "datasetCount": 0, + "files": [] + }, + "message": "", + "collection_id": "collection_id" +} ``` -Your results should be available in `output.json` +That contains the **results** of the query, which was 44. From 827781327de2bf3a21dda7b95e9de1709bbc2e40 Mon Sep 17 00:00:00 2001 From: Andy Rae Date: Thu, 6 Feb 2025 21:01:14 +0000 Subject: [PATCH 3/5] Remove error --- website/pages/bunny/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/pages/bunny/quickstart.mdx b/website/pages/bunny/quickstart.mdx index 9b10e2d..a36f731 100644 --- a/website/pages/bunny/quickstart.mdx +++ b/website/pages/bunny/quickstart.mdx @@ -16,7 +16,7 @@ This guide will help you quickly set up a local OMOP CDM database and run a quer ### 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: +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 From 2ac6c177eeabf7e7ca8086eeee59ad6415a376af Mon Sep 17 00:00:00 2001 From: Andy Rae Date: Thu, 6 Feb 2025 21:08:44 +0000 Subject: [PATCH 4/5] Add a cleanup --- website/pages/bunny/quickstart.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/website/pages/bunny/quickstart.mdx b/website/pages/bunny/quickstart.mdx index a36f731..f10e879 100644 --- a/website/pages/bunny/quickstart.mdx +++ b/website/pages/bunny/quickstart.mdx @@ -32,6 +32,8 @@ This will start the database, initialise it with a synthetic OMOP CDM dataset, a 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" @@ -86,6 +88,20 @@ You should see output like the following: That contains the **results** of the query, which was 44. +### Clean up + +```bash copy +docker compose -f bunny-demo.compose.yml down +``` + +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 +``` + ## Next Steps From 3e622e277ded3d00b322643ab9bbf8880ef96633 Mon Sep 17 00:00:00 2001 From: Andy Rae Date: Thu, 6 Feb 2025 21:21:19 +0000 Subject: [PATCH 5/5] Update index --- website/pages/index.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) 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/"/> +