[ENH] Add environment variables for API root paths and query site hea…

…der 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 <[email protected]> * add defaults for variables we don't require user to change in docker-compose.yml --------- Co-authored-by: Sebastian Urchs <[email protected]>
neurobagel · Feb 14, 2025 · db90c46 · db90c46
1 parent d5f6c83
commit db90c46
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 13 deletions.
diff --git 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
@@ -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
+`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
diff --git 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 ----