From 27ee42bf78b59aa6208c10f3dde548bba01a5a04 Mon Sep 17 00:00:00 2001 From: Alyssa Dai Date: Sat, 9 Sep 2023 23:19:37 -0400 Subject: [PATCH] [REF] Remove environment variable table from README (#168) * 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 --- .template-env | 4 +- README.md | 86 ++++++------------------------ docs/api_environment_variables.tsv | 18 +++++++ 3 files changed, 35 insertions(+), 73 deletions(-) create mode 100644 docs/api_environment_variables.tsv diff --git a/.template-env b/.template-env index 2ce27ee..3b2dd9b 100644 --- a/.template-env +++ b/.template-env @@ -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. @@ -17,4 +18,3 @@ API_QUERY_URL=http://localhost:8000/ # NB_GRAPH_PORT=5820 # NB_QUERY_TAG=latest # NB_QUERY_PORT_HOST=3000 - diff --git a/README.md b/README.md index 900bdd1..61a8a93 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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/). @@ -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 diff --git a/docs/api_environment_variables.tsv b/docs/api_environment_variables.tsv new file mode 100644 index 0000000..9b9ed65 --- /dev/null +++ b/docs/api_environment_variables.tsv @@ -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 \ No newline at end of file