Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[REF] Change the linked examples to recipe repo #158

Merged
merged 8 commits into from
Feb 3, 2024
27 changes: 18 additions & 9 deletions docs/infrastructure.md
surchs marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -84,15 +84,24 @@ We have tested the following options:
We recommend launching the Neurobagel API and your graph backend instance using `docker compose`.
(To install the API from source, see [these instructions](https://github.com/neurobagel/api/blob/main/README.md#local-installation).)

### Clone the API repo
### Clone the configuration file templates

The [`neurobagel/recipes`](https://github.com/neurobagel/recipes) repository contains templates of all files needed for configuring different types of Neurobagel deployments.

Configuration files for setting up a single Neurobagel node are found in the [`local_node`](https://github.com/neurobagel/recipes/tree/main/local_node) subdirectory.
**You can follow the below steps directly in this subdirectory, or in a new directory outside of the repository.**
```bash
git clone https://github.com/neurobagel/api.git
git clone [email protected]:neurobagel/recipes.git
surchs marked this conversation as resolved.
Show resolved Hide resolved
surchs marked this conversation as resolved.
Show resolved Hide resolved
cd recipes/local_node
```

### Set the environment variables
Create a `.env` file in the root of the repository to house the environment variables used by the Neurobagel API-graph network.
Create a `.env` file to house the environment variables used by the Neurobagel API-graph network.

The `neurobagel/api` repo contains a [`.template-env`](https://github.com/neurobagel/api/blob/main/.template-env) to get you started. Copy and rename this file to `.env` and then edit it as needed.
The `neurobagel/recipes` repo contains a
[`template.env`](https://github.com/neurobagel/recipes/blob/main/local_node/template.env)
in [the `local_node` recipe](https://github.com/neurobagel/recipes/tree/main/local_node)
to get you started. Copy and rename this file to `.env` and then edit it as needed.

Below are all the possible Neurobagel environment variables that can be set in `.env`.

Expand Down Expand Up @@ -151,7 +160,7 @@ For a local deployment, we recommend to **explicitly set** at least the followin
To spin up the Neurobagel API and graph backend containers using Docker Compose,
ensure that both [docker](https://docs.docker.com/get-docker/) and [docker compose](https://docs.docker.com/compose/install/) are installed.

Run the following in the repository root (where the `docker-compose.yml` file is) to launch the containers:
Run the following in the directory containing both the `docker-compose.yml` file from [the local_nodes recipe](https://github.com/neurobagel/recipes/tree/main/local_node) and the .env file you just created.

!!! tip
Double check that any environment variables you have customized in `.env` are resolved with your expected values using the command `docker compose config`.
Expand Down Expand Up @@ -418,7 +427,7 @@ with a name of `test_data`.

## Uploading data to the graph

The `neurobagel/api` repo contains a helper script [`add_data_to_graph.sh`](https://github.com/neurobagel/api/blob/main/add_data_to_graph.sh) for automatically uploading all JSONLD and/or TTL files (i.e., graph-ready data) in a directory to a specific graph database, with the option to clear the existing data in the database first.
The `neurobagel/api` repo contains a helper script [`add_data_to_graph.sh`](https://github.com/neurobagel/recipes/blob/main/scripts/add_data_to_graph.sh) for automatically uploading all JSONLD and/or TTL files (i.e., graph-ready data) in a directory to a specific graph database, with the option to clear the existing data in the database first.
surchs marked this conversation as resolved.
Show resolved Hide resolved
In the context of Neurobagel, each `.jsonld` file is expected to correspond to a single **dataset**.

To view all the command line arguments for add_data_to_graph.sh:
Expand Down Expand Up @@ -522,11 +531,11 @@ You can choose to omit the flag or explicitly specify `--no-clear-data` (default

The participant variables modeled by Neurobagel are named using Neurobagel's own vocabulary (for more information, see this page on [controlled terms](./term_naming_standards.md)).
This vocabulary, which defines internal relationships between vocabulary terms,
is serialized in the file [`nb_vocab.ttl`](https://github.com/neurobagel/api/blob/main/vocab/nb_vocab.ttl) available from the `neurobagel/api` repository.
is serialized in the file [`nb_vocab.ttl`](https://github.com/neurobagel/recipes/blob/main/vocab/nb_vocab.ttl) available from the `neurobagel/recipes` repository.
If you have cloned the api repository, you will already have downloaded the vocabulary file.
surchs marked this conversation as resolved.
Show resolved Hide resolved

**The `nb_vocab.ttl` file should be added to every created Neurobagel graph database.**
This can be done using the same script we used to upload the dataset JSONLD files, [`add_data_to_graph.sh`](https://github.com/neurobagel/api/blob/main/add_data_to_graph.sh), which adds all `.ttl` and/or `.jsonld` files in a given directory to the specified graph.
This can be done using the same script we used to upload the dataset JSONLD files, [`add_data_to_graph.sh`](https://github.com/neurobagel/recipes/blob/main/scripts/add_data_to_graph.sh), which adds all `.ttl` and/or `.jsonld` files in a given directory to the specified graph.

Run the following code (assumes you are in the `api` directory):
surchs marked this conversation as resolved.
Show resolved Hide resolved

Expand Down Expand Up @@ -641,7 +650,7 @@ To make the Neurobagel API accessible by a frontend tool such as our [browser qu
you must explicitly specify the origin(s) for the frontend using `NB_API_ALLOWED_ORIGINS` in `.env`.
For detailed instructions regarding the query tool see [Running cohort queries](query_tool.md).
surchs marked this conversation as resolved.
Show resolved Hide resolved

For example, the [`.template-env`](https://github.com/neurobagel/api/blob/main/.template-env) file in the Neurobagel API repo assumes you want to allow API requests from a query tool hosted at a specific port on `localhost` (see the [Docker Compose section](#docker-compose)).
For example, the [`template.env`](https://github.com/neurobagel/recipes/blob/main/local_node/template.env) file in the Neurobagel API repo assumes you want to allow API requests from a query tool hosted at a specific port on `localhost` (see the [Docker Compose section](#docker-compose)).
surchs marked this conversation as resolved.
Show resolved Hide resolved

!!! example "More examples of `NB_API_ALLOWED_ORIGINS`"

Expand Down
Loading