From db90c4637925efe12dbdb105e3ba3e24904b867c Mon Sep 17 00:00:00 2001 From: Alyssa Dai Date: Fri, 14 Feb 2025 12:04:06 -0500 Subject: [PATCH] [ENH] Add environment variables for API root paths and query site header script (#106) * add NB_NAPI_ROOT_PATH, NB_FAPI_ROOT_PATH to .env * reword and update environment variable table * add NB_QUERY_HEADER_SCRIPT + fix missing NB_MIN_CELL_SIZE * revert previous change from NB_NAPI_ALLOWED_ORIGINS -> NB_API_ALLOWED_ORIGINS * clarify experimental variables * rename env var * rename NB_FAPI_ROOT_PATH * Update template.env comments Co-authored-by: Sebastian Urchs * add defaults for variables we don't require user to change in docker-compose.yml --------- Co-authored-by: Sebastian Urchs --- docker-compose.yml | 6 +++++- docs/neurobagel_environment_variables.tsv | 11 ++++++---- template.env | 26 ++++++++++++++++------- 3 files changed, 30 insertions(+), 13 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 0dd3a62..824dc03 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -13,8 +13,10 @@ services: NB_GRAPH_PORT: 7200 NB_GRAPH_DB: ${NB_GRAPH_DB:-repositories/my_db} NB_RETURN_AGG: ${NB_RETURN_AGG:-true} + NB_MIN_CELL_SIZE: ${NB_MIN_CELL_SIZE:-0} NB_API_PORT: 8000 - NB_API_ALLOWED_ORIGINS: ${NB_NAPI_ALLOWED_ORIGINS} + NB_NAPI_BASE_PATH: ${NB_NAPI_BASE_PATH} + NB_API_ALLOWED_ORIGINS: ${NB_NAPI_ALLOWED_ORIGINS:-"*"} NB_ENABLE_AUTH: ${NB_ENABLE_AUTH:-false} NB_QUERY_CLIENT_ID: ${NB_QUERY_CLIENT_ID} volumes: @@ -58,6 +60,7 @@ services: - "./local_nb_nodes.json:/usr/src/local_nb_nodes.json:ro" environment: NB_API_PORT: 8000 + NB_FAPI_BASE_PATH: ${NB_FAPI_BASE_PATH} NB_FEDERATE_REMOTE_PUBLIC_NODES: ${NB_FEDERATE_REMOTE_PUBLIC_NODES:-True} NB_ENABLE_AUTH: ${NB_ENABLE_AUTH:-false} NB_QUERY_CLIENT_ID: ${NB_QUERY_CLIENT_ID} @@ -74,6 +77,7 @@ services: NB_QUERY_APP_BASE_PATH: ${NB_QUERY_APP_BASE_PATH:-/} NB_ENABLE_AUTH: ${NB_ENABLE_AUTH:-false} NB_QUERY_CLIENT_ID: ${NB_QUERY_CLIENT_ID} + NB_QUERY_HEADER_SCRIPT: ${NB_QUERY_HEADER_SCRIPT} secrets: db_admin_password: diff --git a/docs/neurobagel_environment_variables.tsv b/docs/neurobagel_environment_variables.tsv index bc34654..126174b 100644 --- a/docs/neurobagel_environment_variables.tsv +++ b/docs/neurobagel_environment_variables.tsv @@ -4,17 +4,20 @@ Environment variable Default needs change? Description Default value if not set `NB_GRAPH_DB` Yes Name to give your graph database (e.g., for a GraphDB database, use the format `repositories/{database_name}`) `repositories/my_db` Docker, Python `LOCAL_GRAPH_DATA` Yes Path on your filesystem to the JSONLD files you want to upload to the graph database `./data` Docker `NB_GRAPH_PORT_HOST` No Port number on the _host machine_ to map the graph server container port to `7200` Docker -`NB_API_ALLOWED_ORIGINS` No Origins allowed to make cross-origin resource sharing requests. Multiple origins must be separated with spaces in a single string enclosed in quotes. "`""""`" Docker, Python +`NB_NAPI_ALLOWED_ORIGINS` No Origins allowed to make cross-origin resource sharing requests. Multiple origins must be separated with spaces in a single string enclosed in quotes. "`""""`" Docker, Python `NB_RETURN_AGG` No Whether to return only aggregate, dataset-level query results (excluding subject/session-level attributes). One of [true, false] `true` Docker, Python `NB_MIN_CELL_SIZE` No Minimum number of matching subjects required for a dataset to be returned as a query match. Datasets with matching subjects <= this number will be excluded from query results. `0` Docker, Python `NB_NAPI_TAG` No Docker image tag for the Neurobagel node API `latest` Docker `NB_NAPI_PORT_HOST` No Port number on the _host machine_ to map the Neurobagel node API container port to `8000` Docker +`NB_NAPI_BASE_PATH` No (If using reverse proxy) The URL path where the node API is served from. Do not include a trailing slash. `""` Docker `NB_FAPI_TAG` No Docker image tag for the Neurobagel federation API `latest` Docker `NB_FAPI_PORT_HOST` No Port number on the _host machine_ to map the Neurobagel federation API container port to `8080` Docker `NB_FEDERATE_REMOTE_PUBLIC_NODES` No If "True", include public nodes in federation. If "False", only locally specified nodes in `local_nb_nodes.json` are queried. `true` Docker, Python +`NB_FAPI_BASE_PATH` No (If using reverse proxy) The URL path where the federation API is served from. Do not include a trailing slash. `""` 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 `NB_API_QUERY_URL` Yes URL (and port number, if needed) of the Neurobagel API that the query tool will send its requests to. The query tool sends requests from a user's machine, so ensure the API URL is provided *as a user would access it from their own machine*. See also the [query tool README](https://github.com/neurobagel/query-tool?tab=readme-ov-file#set-the-environment-variables). - Docker -`NB_QUERY_APP_BASE_PATH` No The URL path for the query tool, determines the specific URL at which the app should be rendered for users to access it `/` Docker -`NB_ENABLE_AUTH` No **(Experimental, for dev deployments only)** Whether to enable authentication for cohort queries. One of [true, false] `false` Docker, Python -`NB_QUERY_CLIENT_ID` No **(Experimental, for dev deployments only)** OAuth client ID for the query tool. Required if NB_ENABLE_AUTH is set to true. - Docker, Python \ No newline at end of file +`NB_QUERY_APP_BASE_PATH` No (If using reverse proxy) The URL path for the query tool, determines the specific URL at which the app should be rendered for users to access it `/` Docker +`NB_QUERY_HEADER_SCRIPT` No (Experimental, for development environments only) Custom script to add to the header section of the query tool site, such as for a GDPR-aware analytics tool. `""` Docker +`NB_ENABLE_AUTH` No **(Experimental, for development environments only)** Whether to enable authentication for cohort queries. One of [true, false] `false` Docker, Python +`NB_QUERY_CLIENT_ID` No **(Experimental, for development environments only)** OAuth client ID for the query tool. Required if NB_ENABLE_AUTH is set to true. - Docker, Python \ No newline at end of file diff --git a/template.env b/template.env index 95429ce..66db91b 100644 --- a/template.env +++ b/template.env @@ -34,21 +34,29 @@ LOCAL_GRAPH_DATA=./data # --------------------------------- # ---- CONFIGURATION FOR n-API ---- -# Origins to allow requests from. To limit to specific origins, replace * with URLs separated by a space. -NB_API_ALLOWED_ORIGINS="*" # Whether to return only aggregate, dataset-level query results (excluding subject/session-level attributes). NB_RETURN_AGG=true # Additional configurable parameters - uncomment to change the defaults +# If using a reverse proxy (NGINX, Caddy, etc.) to serve the n-API from a specific path other than the root (e.g., mynode.org/napi), +# set NB_NAPI_BASE_PATH to your custom base path (e.g., NB_NAPI_BASE_PATH="/napi"). +# Do not include a trailing slash! +# NB_NAPI_BASE_PATH="" # Change NB_NAPI_PORT_HOST if port 8000 is already in use on the machine # NB_NAPI_PORT_HOST=8000 # Minimum number of matching subjects required for a dataset to be returned as a query match. Datasets with matching subjects <= this number will be excluded from query results. # NB_MIN_CELL_SIZE=0 +# Origins that can send requests to the n-API. To limit to specific origins, replace * with URLs separated by a space. +# NB_NAPI_ALLOWED_ORIGINS="*" # NB_NAPI_TAG=latest # --------------------------------- # ---- CONFIGURATION FOR f-API ---- # Additional configurable parameters - uncomment to change the defaults +# If using a reverse proxy (NGINX, Caddy, etc.) to serve the f-API from a specific path other than the root (e.g., mynode.org/fapi), +# set NB_FAPI_BASE_PATH to your custom base path (e.g., NB_FAPI_BASE_PATH="/fapi"). +# Do not include a trailing slash! +# NB_FAPI_BASE_PATH="" # Change NB_FAPI_PORT_HOST if port 8080 is already in use on the machine # NB_FAPI_PORT_HOST=8080 # NB_FAPI_TAG=latest @@ -67,22 +75,24 @@ NB_RETURN_AGG=true NB_API_QUERY_URL=http://XX.XX.XX.XX # Additional configurable parameters - uncomment to change the defaults -# Change NB_QUERY_APP_BASE_PATH if you're using a proxy server (NGINX, Caddy, etc.) and have configured it so that the query tool is accessible at a path other than the root (`/`). -# e.g., if your proxy server is set up so that mynode.org/querytool points to the query tool, you would set NB_QUERY_APP_BASE_PATH=/querytool +# If using a reverse proxy (NGINX, Caddy, etc.) to serve the query tool from a specific path other than the root (e.g., mynode.org/querytool), +# set NB_QUERY_APP_BASE_PATH to your custom base path (e.g., NB_QUERY_APP_BASE_PATH="/querytool"). # NB_QUERY_APP_BASE_PATH=/ # Change NB_QUERY_PORT_HOST if port 3000 is already in use on the machine # NB_QUERY_PORT_HOST=3000 # NB_QUERY_TAG=latest # -------------------------------------- -# ---- SECURITY CONFIGURATION ---- -# NOTE: EXPERIMENTAL, THESE SETTINGS ARE UNDER ACTIVE DEVELOPMENT AND CURRENTLY SHOULD BE MODIFIED FOR DEV DEPLOYMENTS ONLY. -# The below settings will be used for both the query tool and the f-API. -# NB_ENABLE_AUTH=false +# ---- EXPERIMENTAL FEATURES ---- +# IMPORTANT: THE BELOW SETTINGS ARE EXPERIMENTAL AND SHOULD NOT BE MODIFIED EXCEPT IN DEVELOPMENT ENVIRONMENTS. +# The below two settings are used by both the query tool and the f-API. +# NB_ENABLE_AUTH=false # If NB_ENABLE_AUTH is set to true, you MUST provide a valid OAuth client ID for your query tool instance. # To obtain an OAuth client ID to enable login with Google, see https://developers.google.com/identity/openid-connect/openid-connect#appsetup. # NB_QUERY_CLIENT_ID=XXXX + +# NB_QUERY_HEADER_SCRIPT="" # -------------------------------- # ---- CONFIGURATION FOR docker compose ----