Skip to content

Commit

Permalink
[ENH] Add query tool to docker compose (#154)
Browse files Browse the repository at this point in the history 
* 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 <[email protected]>

* 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 <[email protected]>
  • Loading branch information
@surchs @alyssadai
surchs and alyssadai authored Sep 6, 2023
1 parent fdf7a5c commit 28f1b0e
Show file tree
Hide file tree
Showing 3 changed files with 33 additions and 16 deletions.
4 changes: 4 additions & 0 deletions .template-env
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

39 changes: 23 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 &dagger; | 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_ &dagger; _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 &dagger; | 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_ &dagger; _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._

Expand All @@ -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:
Expand Down
6 changes: 6 additions & 0 deletions docker-compose.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}/}"

0 comments on commit 28f1b0e

Please sign in to comment.