[ENH] Document minimum cell size configuration, minor fixes (#261)

* fix numbered bullet point ordering * update security variables section * link to passwords/security vars section in getting started * add notes on graph store passwords and dynamic variables * link to restarting services after update * remove relative links from link checker ignore patterns * update info on graph store passwords Co-authored-by: Sebastian Urchs <[email protected]> * update getting started * update info on resetting GraphDB * switch to markdown syntax for images w/ width specification Co-authored-by: Sebastian Urchs <[email protected]> * add markdown extension for continuing numbered lists --------- Co-authored-by: Sebastian Urchs <[email protected]>
neurobagel · Jan 17, 2025 · 0c7d39a · 0c7d39a
1 parent 4070966
commit 0c7d39a
Show file tree

Hide file tree

Showing 6 changed files with 57 additions and 39 deletions.
diff --git a/docs/user_guide/annotation_tool.md b/docs/user_guide/annotation_tool.md
@@ -61,12 +61,12 @@ A good way to manage different node versions is to use the [node version manager
 <!--
 NOTE: Raw HTML is used for this set of images as in the README to restrict screenshot size, but mkdocs doesn't play well with the relative path links (see https://github.com/mkdocs/mkdocs/issues/991), so the paths have been modified to start with `../` instead of `./` so mkdocs can find the right files.
 -->
-<img width="300" src="../imgs/annotate/readme_navbar.png" alt="Annotation tool navbar screenshot">
-<img width="300" src="../imgs/annotate/readme_nextpage_button.png" alt="Annotation tool next page button screenshot">
+![Annotation tool navbar screenshot](../imgs/annotate/readme_navbar.png){ width="300"}
+![Annotation tool next page button screenshot](../imgs/annotate/readme_nextpage_button.png){ width="300"}
 
 There are two means of moving forward to the next step in the annotation tool's workflow: (1) the <span style="color:green;">navbar</span> at the top right of the screen which features the page names, and (2) the <span style="color:green;">next page buttons</span> on the bottom right of each page.
 
-<img width="300" src="../imgs/annotate/readme_nextpage_instructions.png" alt="Annotation tool next page button screenshot">
+![Annotation tool next page button screenshot](../imgs/annotate/readme_nextpage_instructions.png){ width="300"}
 
 However, special criteria for each page need to be be met in order to move forward. Instructions are offered above the <span style="color:green;">next page button</span> while those conditions are still as of yet unmet. (These are denoted below under _Next page criteria_.) After having done so, the next page's name in the <span style="color:green;">navbar</span> will turn from gray to green, and the <span style="color:green;">next page button</span> will turn from gray to green as well.
 

diff --git a/docs/user_guide/config.md b/docs/user_guide/config.md
@@ -86,32 +86,45 @@ Below are all the possible Neurobagel environment variables that can be set in `
 
 ### Change security relevant variables
 
-For security purposes, we recommend the following additional steps for configuring your node if you are using a deployment profile that includes a graph store:
+For security and best practice purposes, follow the below additional steps to configure your node if you are using a deployment profile that includes a graph store:
 
-1. Review and change the values of the following variables in `.env`:
+1. **Change the values** of the following variables in `.env` from their defaults:
     - `NB_GRAPH_USERNAME`
-    - `NB_GRAPH_SECRETS_PATH`
     - `NB_GRAPH_DB`
-    - `NB_RETURN_AGG`
 
-2. Change the default passwords for the `admin` superuser and newly created graph database user (`NB_GRAPH_USERNAME`) for your graph store. 
-These are set to the contents of files called `NB_GRAPH_ADMIN_PASSWORD.txt` and `NB_GRAPH_PASSWORD.txt`, respectively, which are found by default in [`./secrets`](https://github.com/neurobagel/recipes/tree/main/secrets) in the Neurobagel recipes repo.
-To change the location of your password files, simply edit the variable `NB_GRAPH_SECRETS_PATH` in `.env` to point to a more secure directory where you have stored the two text files.
+2. **Replace the default passwords** for the `admin` superuser and the newly created graph database user (`NB_GRAPH_USERNAME`) for your graph store with your own secure passwords. 
 
-    Make sure to use secure passwords for `NB_GRAPH_ADMIN_PASSWORD.txt` and `NB_GRAPH_PASSWORD.txt`.
+    ??? warning "Already launched a Neurobagel node?"
+        If you have already completed the [Getting started](getting_started.md#the-neurobagel-node-deployment-recipe) instructions and launched a Neurobagel Docker Compose stack for the first time,
+        you will have to [reset your graph store](maintaining.md#resetting-your-graphdb-instance) before proceeding with this step. Don't worry, any other configuration changes you've made will be applied when you re-launch your node.
 
-    To generate a random password in the terminal, you can use:
+    - These passwords are stored in the directory defined under `NB_GRAPH_SECRETS_PATH` in `.env` ([`./secrets`](https://github.com/neurobagel/recipes/tree/main/secrets) by default), as the file contents of `NB_GRAPH_ADMIN_PASSWORD.txt` and `NB_GRAPH_PASSWORD.txt`, respectively.
+    - To generate a random password in the terminal, you can use:
+      ```bash
+      openssl rand -hex 16
+      ```
 
-    ```bash
-    openssl rand -hex 16
-    ```
+    - (Optional) Change the directory where your password files are stored by editing the variable `NB_GRAPH_SECRETS_PATH` in `.env`.
+
+    ??? info "Graph store passwords are not meant for use by node query users"
+        The passwords specified in the deployment recipe are only used internally by the scripts that (automatically) set up and update the graph store, 
+        or to interact directly with the graph store (e.g., to modify database configuration or data).
+        The passwords are also used to secure internal communication between your graph and its node API,
+        such that an external user cannot query your graph directly.
 
     ??? info "Passwords are handled as Docker secrets"
 
         The contents of `NB_GRAPH_ADMIN_PASSWORD.txt` and `NB_GRAPH_PASSWORD.txt` are passed to Neurobagel containers as [Docker secrets](https://docs.docker.com/reference/compose-file/secrets/).
         This ensures that your passwords are not exposed in the container logs or in the `docker-compose.yml` file.
 
         Make sure to not share your password files with others.
+
+2. **Review and change as necessary** values of the following variables in `.env` from their defaults, based on your data sharing requirements:
+    - `NB_RETURN_AGG`
+    - `NB_MIN_CELL_SIZE`
+    !!! info
+        These variables are modifiable after node initialization; you can [change their values at any time](maintaining.md#restarting-services-after-an-update).
+
 
 ## Configuring local node names and URLs for federation
 

diff --git a/docs/user_guide/getting_started.md b/docs/user_guide/getting_started.md
@@ -88,45 +88,49 @@ 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
 
-    You **must** replace the placeholder value for `NB_API_QUERY_URL`in the `.env` file
+3. Change the placeholder value of `NB_API_QUERY_URL` in the `.env` file
 
     ```bash
     NB_API_QUERY_URL=http://XX.XX.XX.XX
     ```
-    with the URL address where the Neurobagel federation API will be accessed:
+   `http://XX.XX.XX.XX` must be replaced with the URL address where the Neurobagel federation API will be accessed:
 
     - 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.
 
-4. (Optional) If you have already [generated Neurobagel JSONLD data files](cli.md), update `LOCAL_GRAPH_DATA` in `.env` to the path containing the data files you wish to add to the graph database.
+#### If you have already have graph-ready data
+At this point, if you have already [generated Neurobagel JSONLD data files](cli.md), you can proceed with the below additional steps before launching Neurobagel:
+
+4. Update `LOCAL_GRAPH_DATA` in `.env` to the path containing the data files you wish to add to the graph database.
 
-    Updating the data in the graph can be done at any time. For more information, see [this section](maintaining.md#updating-the-data-in-your-graph).
+    You can update these data in the graph at any time. For more information, see [this section](maintaining.md#updating-the-data-in-your-graph).
+
+5. Change the default credentials for your graph database following [these instructions](config.md#change-security-relevant-variables).
 
 !!! info
 
-    This is the minimal configuration you need to make before you can launch Neurobagel.
-    In most cases, and especially when you are deploying Neurobagel for other users,
-    you will have to make additional configurations. 
+    This section provide a minimal configuration for launching Neurobagel.
+    In most cases, particularly when deploying Neurobagel for other users,
+    additional configurations may be necessary to ensure optimal usability and security of your node.
 
     Please refer to [our detailed documentation](config.md#environment-variables) for a complete overview of 
     configuration options.
 
 ## Launch Neurobagel
 
-Once you have edited the `.env` and optionally the `local_nb_nodes.json` file, 
-you can launch your own Neurobagel node with the following `docker compose` command:
+Once you have completed at least steps 1 to 3 [above](#the-neurobagel-node-deployment-recipe), 
+you can launch your own Neurobagel node using Docker Compose:
 
 ```bash
 docker compose up -d
 ```
 ??? info "Explanation"
     This is a shorthand for: `docker compose --profile full_stack up -d`
 
-this will:
+This will:
 
 - pull the required Docker images (if you haven't pulled them before)
 - launch the containers for [the Neurobagel services](config.md#available-services) using the default `full_stack` [service profile](config.md#available-profiles)

diff --git a/docs/user_guide/maintaining.md b/docs/user_guide/maintaining.md
@@ -94,7 +94,6 @@ Once you have generated or updated the JSONLD files you want to upload, to updat
     ```bash
     docker compose --profile full_stack down
     ```
-
    (or, replace `full_stack` with the profile you are using)
 
 2. Update the data files in the directory specified by the `LOCAL_GRAPH_DATA` variable in `.env`, or simply change the path to a directory containing your JSONLD files.
@@ -213,34 +212,36 @@ follow these steps:
 
     If you are not using the `full_stack` profile, replace `full_stack` with the name of the profile you are using.
 
-2. Delete the docker volume that contains the GraphDB data for your node.
+2. Delete the Docker volume that contains the GraphDB data for your node.
 
     ```bash
     docker volume rm neurobagel_node_graphdb_home
     ```
 
-    replace `neurobagel_node_graphdb_home` with the name of the volume that was created for your node.
+    Replace `neurobagel_node_graphdb_home` with the name of the volume created for your node.
     It is usually named `<project_name>_graphdb_home`
-    where `<project_name>` is the name of your docker compose stack
-    as defined in `COMPOSE_PROJECT_NAME` in the `.env` file.
+    where `<project_name>` is the name of your Docker Compose stack
+    as defined in `COMPOSE_PROJECT_NAME` in your `.env` file.
+
+    ??? tip "`docker volume ls` lists all volumes on your system"
+
+        You can use the `docker volume ls` command to list all volumes on your system.
+        This will help you identify the name of the volume that was created for your Neurobagel node.
 
-3. Start your Neurobagel node again.
+
+3. Launch your Neurobagel node again.
 
     ```bash
     docker compose --profile full_stack up -d
     ```
 
     If you are not using the `full_stack` profile, replace `full_stack` with the name of the profile you are using.
 
-!!! info "Use `docker volume ls` to list all volumes on your system"
-
-    You can use the `docker volume ls` command to list all volumes on your system.
-    This will help you identify the name of the volume that was created for your Neurobagel node.
-
 Some examples of when you might want to do this:
 
 - You started but did not complete Neurobagel node setup previously and want to ensure you are using up-to-date instructions and recommended configuration options
 - Your local node has stopped working after a configuration change to your graph database (e.g., your Neurobagel node API no longer starts or responds with an error, but you have confirmed all environment variables you have set should be correct)
+- You need to modify credentials for your graph store
 
 !!! warning
 

diff --git a/md_link_check_config.json b/md_link_check_config.json
@@ -3,7 +3,6 @@
         {"pattern": "http://neurobagel.org/vocab/.*"},
         {"pattern": "http://neurobagel.org/graph/"},
         {"pattern": "http://neurobagel.org/graph/"},
-        {"pattern": "^../.*"},
         {"pattern": ".*localhost.*"},
         {"pattern": "https://api.neurobagel.org/.*"},
         {"pattern": "http://purl.org/nidash/nidm#.*"},

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -61,7 +61,8 @@ markdown_extensions:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.superfences
   - pymdownx.tabbed:
-      alternate_style: true 
+      alternate_style: true
+  - sane_lists  # for continuing numbered lists as specified after a paragraph
   - tables