From 28f1b0e3cf560d866baebf124c7a880cae515bab Mon Sep 17 00:00:00 2001 From: Sebastian Urchs Date: Wed, 6 Sep 2023 12:54:33 -0400 Subject: [PATCH] [ENH] Add query tool to docker compose (#154) * Add query tool to docker stack * Basic docs update for query tool * Add new env vars to table * Apply suggestions from code review Co-authored-by: Alyssa Dai * Add API_QUERY_URL to .template-env * Ensure trailing slash in default API_QUERY_URL * Add doc on API_QUERY_URL --------- Co-authored-by: Alyssa Dai --- .template-env | 4 ++++ README.md | 39 +++++++++++++++++++++++---------------- docker-compose.yml | 6 ++++++ 3 files changed, 33 insertions(+), 16 deletions(-) diff --git a/.template-env b/.template-env index 93078cc..2ce27ee 100644 --- a/.template-env +++ b/.template-env @@ -6,6 +6,7 @@ NB_RETURN_AGG=true NB_API_TAG=latest NB_API_ALLOWED_ORIGINS="https://localhost:3000 http://localhost:3000" # Example of allowing multiple origins, edit as needed for your own setup NB_GRAPH_IMG=stardog/stardog:8.2.2-java11-preview +API_QUERY_URL=http://localhost:8000/ ## ADDITIONAL CONFIGURABLE PARAMETERS: Uncomment and modify values of the below variables as needed to use non-default values. # NB_API_PORT_HOST=8000 # NB_API_PORT=8000 @@ -14,3 +15,6 @@ NB_GRAPH_IMG=stardog/stardog:8.2.2-java11-preview # NB_GRAPH_ADDRESS=graph # NB_GRAPH_PORT_HOST=5820 # NB_GRAPH_PORT=5820 +# NB_QUERY_TAG=latest +# NB_QUERY_PORT_HOST=3000 + diff --git a/README.md b/README.md index 22f4b5a..2544337 100644 --- a/README.md +++ b/README.md @@ -55,22 +55,25 @@ To run API requests against a graph, at least two environment variables must be This repository contains a [template `.env` file](/.template-env) that you can copy and edit. Below are explanations of all the possible Neurobagel environment variables that you can set in `.env`, depending on your mode of installation of the API and graph server software. -| Environment variable | Required in .env? | Description | Default value if not set | Relevant installation mode(s) | -| ------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------- | -| `NB_GRAPH_USERNAME` | Yes | Username to access Stardog graph database that API will communicate with | - | Docker, Python | -| `NB_GRAPH_PASSWORD` | Yes | Password to access Stardog graph database that API will communicate with | - | Docker, Python | -| `NB_GRAPH_ADDRESS` | No | IP address for the graph database (or container name, if graph is hosted locally) | `206.12.99.17` (`graph`) ** | Docker, Python | -| `NB_GRAPH_DB` | No | Name of graph database endpoint to query (e.g., for a Stardog database, this will take the format of `{database_name}/query`) | `test_data/query` | Docker, Python | -| `NB_RETURN_AGG` | No | Whether to return only dataset-level query results (including data locations) and exclude subject-level attributes. One of [true, false] | `true` | Docker, Python | -| `NB_API_TAG` | No | Tag for API Docker image | `latest` | Docker | -| `NB_API_PORT_HOST` | No | Port number on the _host machine_ to map the API container port to | `8000` | Docker | -| `NB_API_PORT` | No | Port number on which to run the API | `8000` | Docker, Python | -| `NB_API_ALLOWED_ORIGINS` | No † | Origins allowed to make [cross-origin resource sharing](https://fastapi.tiangolo.com/tutorial/cors/) requests. Multiple origins must be separated with spaces in a single string enclosed in quotes. _NOTE: To make the API accessible from a frontend query tool, the origin must be explicitly set. See_ † _for more info_ | `""` | Docker, Python | -| `NB_GRAPH_IMG` | No | Graph server Docker image | `stardog/stardog:8.2.2-java11-preview` | Docker | -| `NB_GRAPH_ROOT_HOST` | No | Path to directory containing a Stardog license file on the _host machine_ | `~/stardog-home` | Docker | -| `NB_GRAPH_ROOT_CONT` | No | Path to directory for graph databases in the _graph server container_ | `/var/opt/stardog` * | Docker | -| `NB_GRAPH_PORT_HOST` | No | Port number on the _host machine_ to map the graph server container port to | `5820` | Docker | -| `NB_GRAPH_PORT` | No | Port number used by the _graph server container_ | `5820` * | Docker, Python | +| Environment variable | Required in .env? | Description | Default value if not set | Relevant installation mode(s) | +| ------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------- | +| `NB_GRAPH_USERNAME` | Yes | Username to access Stardog graph database that API will communicate with | - | Docker, Python | +| `NB_GRAPH_PASSWORD` | Yes | Password to access Stardog graph database that API will communicate with | - | Docker, Python | +| `NB_GRAPH_ADDRESS` | No | IP address for the graph database (or container name, if graph is hosted locally) | `206.12.99.17` (`graph`) ** | Docker, Python | +| `NB_GRAPH_DB` | No | Name of graph database endpoint to query (e.g., for a Stardog database, this will take the format of `{database_name}/query`) | `test_data/query` | Docker, Python | +| `NB_RETURN_AGG` | No | Whether to return only dataset-level query results (including data locations) and exclude subject-level attributes. One of [true, false] | `true` | Docker, Python | +| `NB_API_TAG` | No | Tag for API Docker image | `latest` | Docker | +| `NB_API_PORT_HOST` | No | Port number on the _host machine_ to map the API container port to | `8000` | Docker | +| `NB_API_PORT` | No | Port number on which to run the API | `8000` | Docker, Python | +| `NB_API_ALLOWED_ORIGINS` | No † | Origins allowed to make [cross-origin resource sharing](https://fastapi.tiangolo.com/tutorial/cors/) requests. Multiple origins must be separated with spaces in a single string enclosed in quotes. _NOTE: To make the API accessible from a frontend query tool, the origin must be explicitly set. See_ † _for more info_ | `""` | Docker, Python | +| `NB_GRAPH_IMG` | No | Graph server Docker image | `stardog/stardog:8.2.2-java11-preview` | Docker | +| `NB_GRAPH_ROOT_HOST` | No | Path to directory containing a Stardog license file on the _host machine_ | `~/stardog-home` | Docker | +| `NB_GRAPH_ROOT_CONT` | No | Path to directory for graph databases in the _graph server container_ | `/var/opt/stardog` * | Docker | +| `NB_GRAPH_PORT_HOST` | No | Port number on the _host machine_ to map the graph server container port to | `5820` | Docker | +| `NB_GRAPH_PORT` | No | Port number used by the _graph server container_ | `5820` * | Docker, Python | +| `NB_QUERY_TAG` | No | Docker image tag for the query tool | `latest` | Docker | +| `NB_QUERY_PORT_HOST` | No | Port number used by the `query_tool` on the _host machine_ | `3000` | Docker | +| `API_QUERY_URL` | Yes, unless default is correct | This is the URL of the API that the query-tool will send its requests to. [See also the query-tool README](https://github.com/neurobagel/query-tool?tab=readme-ov-file#set-the-environment-variables). **Has** to end in a forward slash `/`! | http://localhost:8000/ | Docker | _* These defaults are configured for a Stardog backend - you should not have to change them if you are running a Stardog backend._ @@ -94,6 +97,10 @@ The `NB_API_ALLOWED_ORIGINS` variable defaults to an empty string (`""`) when un However, in many cases you may want to make the API accessible by a frontend tool such as our [browser query tool](https://github.com/neurobagel/query-tool). To do so, you must explicitly specify the origin(s) for the frontend using `NB_API_ALLOWED_ORIGINS` in `.env`. +When you [locally deploy the API with `docker compose`](#docker), you may also deploy a local version of the +Neurobagel graphical query tool. By default you can reach +your local query tool at http://localhost:3000 once it is running. + For example, the `.template-env` file in this repo assumes you want to allow API requests from a query tool hosted at a specific port on `localhost`. Other examples: diff --git a/docker-compose.yml b/docker-compose.yml index 21aee43..ccab8e0 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -19,3 +19,9 @@ services: - "${NB_GRAPH_ROOT_HOST:-~/stardog-home}:${NB_GRAPH_ROOT_CONT:-/var/opt/stardog}" ports: - "${NB_GRAPH_PORT_HOST:-5820}:${NB_GRAPH_PORT:-5820}" + query: + image: "neurobagel/query_tool:${NB_QUERY_TAG:-latest}" + ports: + - "${NB_QUERY_PORT_HOST:-3000}:3000" + environment: + - API_QUERY_URL: "${API_QUERY_URL:-http://localhost:${NB_API_PORT_HOST:-8000}/}"