Skip to content

Commit

Permalink
[REF] Remove environment variable table from README (#168)
Browse files Browse the repository at this point in the history 
* add separate TSV for environment variables

* add info for API_QUERY_URL to env var table

* clarifications in template .env and env var TSV

* remove env var table from README and move query tool note

* reformat README admonitions

* add NB_QUERY_TAG and NB_QUERY_PORT_HOST to env var TSV
  • Loading branch information
@alyssadai
alyssadai committed Sep 10, 2023
1 parent 7a3019e commit 27ee42b
Show file tree
Hide file tree
Showing 3 changed files with 35 additions and 73 deletions.
4 changes: 2 additions & 2 deletions .template-env
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# THIS IS A TEMPLATE .env FILE. MAKE A COPY OF THIS FILE NAMED .env AND MODIFY VALUES AS NEEDED.
# For more info on each variable, see https://neurobagel.org/infrastructure/#set-the-environment-variables
NB_GRAPH_USERNAME=DBUSER # REPLACE DBUSER WITH YOUR GRAPH DATABASE USERNAME
NB_GRAPH_PASSWORD=DBPASSWORD # REPLACE DBPASSWORD WITH YOUR GRAPH DATABASE PASSWORD
NB_GRAPH_DB=test_data/query
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_API_ALLOWED_ORIGINS="https://localhost:3000 http://localhost:3000" # e.g., allow multiple origins from a query tool deployed locally with default port settings; edit as needed for your 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.
Expand All @@ -17,4 +18,3 @@ API_QUERY_URL=http://localhost:8000/
# NB_GRAPH_PORT=5820
# NB_QUERY_TAG=latest
# NB_QUERY_PORT_HOST=3000

86 changes: 15 additions & 71 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,7 @@ The Neurobagel API is a REST API, developed in [Python](https://www.python.org/)
- [Quickstart](#quickstart)
- [Local installation](#local-installation)
- [Environment variables](#set-the-environment-variables)
- [Using a graphical query tool](#using-a-graphical-query-tool-to-send-api-requests)
- [Docker](#docker)
- [Docker (recommended)](#docker)
- [Python](#python)
- [Testing](#testing)
- [License](#license)
Expand All @@ -48,80 +47,19 @@ git clone https://github.com/neurobagel/api.git
```

### Set the environment variables
Create a file called `.env` in the root of the repository will house the environment variables used by the app.

To run API requests against a graph, at least two environment variables must be set, `NB_GRAPH_USERNAME` and `NB_GRAPH_PASSWORD`.

Create a file called `.env` in the root of the repository to store the environment variables used by the app.
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, Python |
| `NB_GRAPH_PORT` | No | Port number used by the _graph server container_ | `5820` * | Docker |
| `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._

_** If using the [docker compose installation route](#option-1-recommended-use-the-docker-composeyaml-file),
do not change `NB_API_ADDRESS` from its default value (`graph`) as this corresponds to the preset container name of the graph database server within the docker compose network._

_† See section [Using a graphical query tool to send API requests](#using-a-graphical-query-tool-to-send-api-requests)_

---
**IMPORTANT:**
- Variables set in the shell environment where the API is launched **_should not be used as a replacement for the `.env` file_** to configure options for the API or graph server software.
- To avoid conflicts related to [Docker's environment variable precedence](https://docs.docker.com/compose/environment-variables/envvars-precedence/),
also ensure that any variables defined in your `.env` are not already set in your current shell environment with **different** values.
---

The below instructions for Docker and Python assume that you have at least set `NB_GRAPH_USERNAME` and `NB_GRAPH_PASSWORD` in your `.env`.

### Using a graphical query tool to send API requests
The `NB_API_ALLOWED_ORIGINS` variable defaults to an empty string (`""`) when unset, meaning that your deployed API will only accessible via direct `curl` requests to the URL where the API is hosted (see [this section](#send-a-test-query-to-the-api) for an example `curl` request).

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`.
To run API requests against a graph, at least two environment variables must be set: `NB_GRAPH_USERNAME` and `NB_GRAPH_PASSWORD`.

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.
**See our [official documentation](https://neurobagel.org/infrastructure/#set-the-environment-variables) for all the possible Neurobagel environment variables that you can set in `.env`, and to check which variables are relevant for your specific installation and setup.**

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:
```bash
# ---- .env file ----
> :warning: **Important:**
> - Variables set in the shell environment where the API is launched **_should not be used as a replacement for the `.env` file_** to configure options for the API or graph server software.
> - To avoid conflicts related to [Docker's environment variable precedence](https://docs.docker.com/compose/environment-variables/envvars-precedence/),
> also ensure that any variables defined in your `.env` are not already set in your current shell environment with **different** values.
# do not allow requests from any frontend origins
NB_API_ALLOWED_ORIGINS="" # this is the default value that will also be set if the variable is excluded from the .env file

# allow requests from only one origin
NB_API_ALLOWED_ORIGINS="https://query.neurobagel.org"

# allow requests from 3 different origins
NB_API_ALLOWED_ORIGINS="https://query.neurobagel.org https://localhost:3000 http://localhost:3000"

# allow requests from any origin - use with caution
NB_API_ALLOWED_ORIGINS="*"
```

**A note for more technical users:** If you have configured an NGINX reverse proxy (or proxy requests to the remote origin) to serve both the API and the query tool from the same origin, you can skip the step of enabling CORS for the API.
For an example, see https://stackoverflow.com/a/28599481.
The below instructions for Docker and Python assume that you have at least set `NB_GRAPH_USERNAME` and `NB_GRAPH_PASSWORD` in your `.env`.

### Docker
First, [install docker](https://docs.docker.com/get-docker/).
Expand All @@ -135,6 +73,12 @@ If needed, update your `.env` file with optional environment variables for the d

**TIP:** Double check that the environment variables are resolved with your expected values using the command `docker compose config`.

> :information_source: **Note: Deploying the Neurobagel query tool**
>
> When you locally deploy the API with `docker compose`, you will also deploy a local version of the [Neurobagel graphical query tool](https://github.com/neurobagel/query-tool).
> By default you can reach your local query tool at http://localhost:3000 once it is running.
> Similarly, the `.template-env` file in this repo also assumes you want to allow API requests from a query tool hosted at a specific port on `localhost`.
Use Docker Compose to spin up the containers by running the following in the repository root (where the `docker-compose.yml` file is):
```bash
docker compose up -d
Expand Down
18 changes: 18 additions & 0 deletions docs/api_environment_variables.tsv
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
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 Docker image tag for the API `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` Yes, if using a frontend query tool ‡ Origins allowed to make cross-origin resource sharing requests. Multiple origins must be separated with spaces in a single string enclosed in quotes. 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, Python
`NB_GRAPH_PORT` No Port number used by the _graph server container_ `5820` * Docker
`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 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). **Must** end in a forward slash `/`! `http://localhost:8000/` Docker

0 comments on commit 27ee42b

Please sign in to comment.