[MNT] Deprecate non-federated query tool config, bump Docker Compose …

…required ver. (#217)

* remove deprecated non-federation query tool from docs

* minor grammatical / formatting edits

* fix required Docker Compose version
- older versions don't support environment variable secrets

* make it clear that local_nb_nodes.json contains n-API info

---------

Co-authored-by: Sebastian Urchs <[email protected]>

docs/api.md

@@ -7,8 +7,8 @@ Neurobagel has two flavours of APIs that can be deployed: **node API** and **fed
 - A [Neurobagel node API (n-API)](https://github.com/neurobagel/api) formulates SPARQL queries based on a set of user-defined parameters to a single connected graph database, and processes returned query results into a user-friendly format.
 - A [Neurobagel federation API (f-API)](https://github.com/neurobagel/federation-api) lets the user sends a single query to _each_ node API it is aware of, and collects and combines the decentralized responses into a single set of query results.
 
-Neurobagel's query tool provides a GUI for querying one or more Neurobagel graphs by sending requests to a Neurobagel API instance (n-API OR f-API). 
-However, HTTP requests can also be sent directly to a Neurobagel API (node or federation).
+Neurobagel's query tool provides a GUI for querying one or more Neurobagel graphs by sending requests to a Neurobagel _federation API_ instance. 
+However, HTTP requests can also be sent directly to any publicly accessible Neurobagel API (node or federation).
 
 ## Public Neurobagel APIs
 

docs/config.md

@@ -10,51 +10,50 @@ for the changes to take effect.
 ## Deployment
 
 ### Available services
-The Neurobagel docker compose recipe includes several services
+The Neurobagel Docker Compose recipe includes several services
 and coordinates them to work together:
 
 (In parentheses are the names of services within the Docker Compose stack)
 
-- [Neurobagel node API](api.md) (`api`): The API that communicates with the graph store and determines 
-    how detailed the response to a query should be.
-- Graph store (`graph`): A third-party RDF store that stores Neurobagel-harmonized data to be queried. At the moment our recipe uses the free tier
+- **[Neurobagel node API/n-API](api.md)** (`api`): The API that communicates with a single graph store and determines 
+    how detailed the response to a query should be from that graph.
+- **Graph store** (`graph`): A third-party RDF store that stores Neurobagel-harmonized data to be queried. At the moment our recipe uses the free tier
     of [GraphDB](https://db-engines.com/en/system/GraphDB) for this.
-- Neurobagel federation API (`federation`): A special API that can federate over
-    multiple Neurobagel nodes to provide a single point of access to multiple nodes.
+- **Neurobagel federation/f-API** (`federation`): A special API that can federate over one or more
+    Neurobagel nodes to provide a single point of access to multiple distributed databases.
     By default it will federate over all public nodes and any local nodes you specify. 
-- [Neurobagel query tool](query_tool.md): A graphical web tool allows users to query the federation API (or node API)
-    and visualize the results. Because the query tool is a static app and is run locally
-    in the users browser, this service simply hosts the app.
+- **[Neurobagel query tool](query_tool.md)** (`query_tool`): A web app that provides a graphical interface for users to query a 
+    federation API and view the results from one or more nodes. Because the query tool is a static app and is run locally
+    in the user's browser, this service simply hosts the app.
 
 ### Available profiles
 Neurobagel offers different deployment profiles that allow you to spin up specific combinations of services (listed below), depending on your use case.
 
 1. `full_stack`: Best profile to get started with Neurobagel. 
-    It includes all services you need to run a single standalone Neurobagel node, including a graphical query tool.
-    :information_source: By default this profile will also federate over all publicly accessible neurobagel nodes.
+    It includes all services you need to run a local Neurobagel node and have the ability to query public nodes, along with a graphical query tool.
        - `api`
        - `graph`
        - `federation`
        - `query_tool`
+    !!! info
+            By default this profile will also federate over all publicly accessible Neurobagel nodes, although this behaviour can be disabled in the f-API using the environment variable [`NB_FEDERATE_REMOTE_PUBLIC_NODES`](#environment-variables).
+
 2. `local_node`: Best profile if you want to run a standalone Neurobagel node
-    and rely on a different deployment for providing federation and the query tool.
-    :information_source: **This is the default profile** if you don't specify one.
+    but rely on a separate deployment for providing federation and a graphical query tool (such as Neurobagel's own hosted public instances).
        - `api`
        - `graph` 
+    !!! info
+         This is the **default profile** if you don't specify one.
+
 3. `local_federation`: Best profile if you already have multiple standalone (local or non-publicly-accessible) Neurobagel node
-    deployments running and you now want to provide federation over them. 
-    :information_source: If you only want to federate over a local node and all public Neurobagel nodes
-    we recommend using the `full_stack` profile to set up your node and federation in one step. If you use the `local_federation` profile, 
-    you will have to [manually configure your `local_nb_nodes.json` file](#local_nb_nodesjson).
-      - `federation`
-      - `query_tool`
-4. `local_node_query`: :warning: Deprecated profile. 
-    This profile lets you create a local node without 
-    federation. The query tool hosted by this deployment will talk only to the
-    local node.
-       - `api`
-       - `graph`
+    deployments running and you now want to provide federation over them.  
+       - `federation`
        - `query_tool`
+    !!! info
+        If you only want to federate over a single local node and all public Neurobagel nodes,
+        we recommend using the `full_stack` profile to set up your node and federation in one step.
+        If you choose to use the `local_federation` profile, 
+        you will have to [manually configure your `local_nb_nodes.json` file](#local_nb_nodesjson).
 
 You can then launch these profiles by using the `--profile` flag with `docker compose`, e.g.:
 
@@ -90,7 +89,7 @@ At minimum, we recommend reviewing and changing the values of the following vari
 > `NB_GRAPH_ADMIN_PASSWORD`  
 > `NB_GRAPH_USERNAME`  
 > `NB_GRAPH_PASSWORD`  
-> `NB_GRAPH_DB` 
+> `NB_GRAPH_DB`
 > `NB_RETURN_AGG`  
 > `NB_API_QUERY_URL`
 
@@ -113,12 +112,15 @@ openssl rand -hex 16
 ## `local_nb_nodes.json`
 
 This file is only used by deployment profiles that include the federation API. 
-`local_nb_nodes.json` contains the URLs and (arbitrary) names of the local nodes you wish to federate over.
+`local_nb_nodes.json` contains the URLs and (arbitrary) names of the _node APIs_ of local nodes you wish to federate over.
 Each node must be denoted by a dictionary `{}` with two key-value pairs:  
-`"NodeName"` for the name of the node,  
-`"ApiURL"` for the URL of the API exposed for that node.  
-Multiple nodes must be wrapped in a list `[]`.
 
+- `"NodeName"`: name of the node
+- `"ApiURL"`: URL of the node API exposed for that node
+
+Multiple nodes must be wrapped in a list `[]`.  
+
+Example: 
 Let's assume there are two local nodes already running on different servers of your institutional network, and you want to set up federation across both nodes:
 
 - a node named `"My Institute"` running on your local computer (localhost), on port `8000` and 
@@ -159,7 +161,7 @@ To add one or more local nodes to the list of nodes known to your `f-API`, simpl
 
 ## Manually setting up a Neurobagel graph backend
 
-The Neurobagel docker compose recipe will automatically setup and configure 
+The Neurobagel Docker Compose recipe will automatically set up and configure 
 all services for you after deployment.
 The automated setup steps are explained in more detail below.
 

docs/getting_started.md

@@ -18,7 +18,7 @@ and are launched with Docker Compose.
 
 !!! danger "Don't install Neurobagel tools directly on your machine"
 
-    Please only use the docker images provided by Neurobagel 
+    Please only use the Docker images provided by Neurobagel 
     (or the third party providers Neurobagel relies on) and only launch
     them with our provided `docker-compose.yml` recipe.
 
@@ -67,7 +67,7 @@ versions on your machine:
 ```bash
 docker --version
 ```
-- `docker compose`: [v2.0.0](https://github.com/docker/compose/releases/tag/v2.0.0) or above
+- `docker compose`: [v2.7.0](https://github.com/docker/compose/releases/tag/v2.7.0) or above
 ```bash
 docker compose version
 ```
@@ -88,20 +88,19 @@ cd recipes
 cp template.env .env
 cp local_nb_nodes.template.json local_nb_nodes.json
 ```
-3. Change `NB_API_QUERY_URL` in the `.env` file 
+3. Change `NB_API_QUERY_URL` in the `.env` file
 
     You **must** replace the placeholder value for `NB_API_QUERY_URL`in the `.env` file
 
     ```bash
     NB_API_QUERY_URL=http://XX.XX.XX.XX
     ```
-    with the address of the machine you are going to deploy Neurobagel on.
+    with the URL address where the Neurobagel federation API will be accessed:
 
-    - If you are deploying Neurobagel **for yourself** or just to try things out locally, 
-   you can use: `NB_API_QUERY_URL=http://localhost:8080` 
-    where `:8080` is the default port for the federation API.
-    - If you are deploying Neurobagel on a server for other users, 
-   you **must** use the IP (and Port) or URL that your users will access the server with. 
+    - If you are deploying Neurobagel for yourself or deploying and trying the services **on your local machine only**, 
+   you can use `NB_API_QUERY_URL=http://localhost:8080`, where `8080` is the [default host port for the federation API](./config.md#environment-variables).
+    - If you are deploying Neurobagel **on a server for other users**, 
+   you must use the IP (and port) or URL intended for your users to access the federation API on the server with.
 
 !!! info
 
@@ -152,9 +151,9 @@ our [service profile documentation](config.md#available-profiles) for details.
 :tada: You are now the proud owner of a running Neurobagel node. Here are some things you can do now:
 
 - Try the Neurobagel node you just deployed by accessing:
-    - your own query tool at  [http://localhost:3000](http://localhost:3000) and reading the [query tool](./query_tool.md) guide
-    - the interactive API docs at [http://localhost:8000/docs](http://localhost:8000/docs) and reading the [API](./api.md) guides
+    - your own query tool at  [http://localhost:3000](http://localhost:3000), and reading the [query tool usage](./query_tool.md#usage) guide
+    - the interactive docs for your node API at [http://localhost:8000/docs](http://localhost:8000/docs), and reading the [API usage](./api.md) guide
 - [Prepare your own dataset](./data_prep.md) for annotation with Neurobagel
 - [Add your own data to your Neurobagel graph](maintaining.md#updating-the-data-in-your-graph) to search
 - Learn about the different [configuration options](config.md) for your Neurobagel node
-- Hopefully all went well, but if you are experiencing issues take a look at our [getting help guide](./getting_help.md)
+- Hopefully all went well, but if you are experiencing issues, see how to [get help](./getting_help.md)