162 lines
4.8 KiB
Markdown
162 lines
4.8 KiB
Markdown
---
|
|
title: Neurobagel
|
|
---
|
|
|
|
NeuroBagel is a collection of containerized services that can be deployed in a variety of way.
|
|
This page describes a deployment using [podman](https://podman.io) and [podman-compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) that is confirmed to be working on machine with a basic Debian 12 installation.
|
|
|
|
For other installation methods, please refer to the [NeuroBagel documentation](https://neurobagel.org/user_guide/getting_started).
|
|
|
|
The following instruction set up a "full-stack" NeuroBagel deployment.
|
|
The contains all relevant components
|
|
|
|
- query front-end
|
|
- federation API
|
|
- node API
|
|
- graph database
|
|
|
|
This setup is suitable for a self-contained deployment, such as the central TRR379 node.
|
|
Other deployments may only need a subset of these services.
|
|
|
|
On the target machine, NeuroBagel services will run "rootless". This means they operate under a dedicated user account with minimal privileges.
|
|
|
|
## Required software
|
|
|
|
Only podman, and its compose feature are needed.
|
|
They can be installed via the system package manager.
|
|
|
|
```bash
|
|
sudo apt install podman podman-compose
|
|
```
|
|
|
|
## User setup
|
|
|
|
We create a dedicated user `neurobagel` on the target machine.
|
|
NeuroBagel will be deployed under this user account, and all software and data will be stored in its HOME directory.
|
|
|
|
```bash
|
|
|
|
# new user, prohibit login, disable password
|
|
sudo adduser neurobagel --disabled-password --disabled-login
|
|
|
|
# allow this user to run prcoess while not logged in
|
|
sudo loginctl enable-linger neurobagel
|
|
|
|
# allow this user to execute systemd commands interactively.
|
|
# this needs XDG_RUNTIME_DIR define.
|
|
# the demo below is for ZSH
|
|
sudo -u neurobagel -s
|
|
cd
|
|
echo 'export XDG_RUNTIME_DIR="/run/user/$UID"' >> ~/.zshrc
|
|
exit
|
|
```
|
|
|
|
## Configure NeuroBagel
|
|
|
|
In the HOME directory of the `neurobagel` user we create the complete runtime environment for the service.
|
|
All configuration is obtained from a Git repository.
|
|
|
|
```bash
|
|
# become the `neurobagel` user
|
|
sudo -u neurobagel -s
|
|
cd
|
|
|
|
# fetch the setup
|
|
git clone https://hub.trr379.de/q02/neurobagel-recipes recipes
|
|
|
|
# create the runtime directory
|
|
mkdir -p run/data/
|
|
mkdir -p run/secrets/
|
|
|
|
# copy over the demo data for testing (can be removed later)
|
|
cp recipes/data/* run/data
|
|
|
|
# generate passwords (using `pwgen` here, but could be any)
|
|
pwgen 20 1 > run/secrets/NB_GRAPH_ADMIN_PASSWORD.txt
|
|
pwgen 20 1 > run/secrets/NB_GRAPH_PASSWORD.txt
|
|
|
|
# configure the the address of the "local" NeuroBagel
|
|
# node to query
|
|
cat << EOT > recipes/local_nb_nodes.json
|
|
[
|
|
{
|
|
"NodeName": "TRR379 central node",
|
|
"ApiURL": "https://nb-cnode.trr379.de"
|
|
}
|
|
]
|
|
EOT
|
|
|
|
```
|
|
## Web server setup
|
|
|
|
NeuroBagel comprises a set of services that run on local ports that are routed to the respective containers.
|
|
Here we use [caddy](https://caddyserver.com) as a reverse proxy to expose the necessary services via `https` at their canonical locations.
|
|
|
|
```bash
|
|
# append the following configuration to the caddy config
|
|
cat << EOT >> /etc/caddy/Caddyfile
|
|
# neurobagel query tool
|
|
nb-query.trr379.de {
|
|
reverse_proxy localhost:13700
|
|
}
|
|
# neurobagel apis
|
|
# graph db api not exposed at 13701
|
|
nb-cnode.trr379.de {
|
|
reverse_proxy localhost:13702
|
|
}
|
|
nb-federation.trr379.de {
|
|
reverse_proxy localhost:13703
|
|
}
|
|
EOT
|
|
```
|
|
|
|
A matching DNS setup must be configured separately.
|
|
|
|
## Manage NeuroBagel with systemd
|
|
|
|
We use [systemd](https://systemd.io) for managing the NeuroBagel service processes, the launch, and logging.
|
|
This makes it largely unnecessary to interact with podman directly, and allows for treating the containerized NeuroBagel like any other system service.
|
|
|
|
The following service unit specification is all that is needed.
|
|
With more recent versions of podman and podman-compose better setups are possible.
|
|
using podman version.
|
|
However, this one is working with the stock versions that come with Debian 12 (podman 4.3.1 and podman-composer 1.0.3) and requires no custom installations.
|
|
|
|
```bash
|
|
mkdir -p .config/systemd/user/
|
|
cat << EOT > .config/systemd/user/neurobagel.service
|
|
[Unit]
|
|
Description=NeuroBagel rootless pod (podman-compose)
|
|
Wants=network-online.target
|
|
After=network-online.target
|
|
|
|
|
|
[Service]
|
|
Type=simple
|
|
WorkingDirectory=/home/neurobagel/recipes
|
|
EnvironmentFile=/home/neurobagel/recipes/trr379.env
|
|
ExecStart=/usr/bin/podman-compose -f ./docker-compose.yml up
|
|
ExecStop=/usr/bin/podman-compose -f ./docker-compose.yml down
|
|
|
|
[Install]
|
|
WantedBy=default.target
|
|
EOT
|
|
```
|
|
|
|
## Launch
|
|
|
|
With this setup in place, we can launch NeuroBagel
|
|
|
|
```bash
|
|
# reload the webserver config to enable the reverse proxy setup
|
|
# (only necessary once)
|
|
sudo systemctl reload caddy
|
|
|
|
# launch the service (pulls all images, loads data, etc).
|
|
# after a minutes the service should be up
|
|
systemctl --user start neurobagel
|
|
|
|
# configure systemd to auto-launch NeuroBagel in case of a
|
|
# system reboot
|
|
systemctl --user enable neurobagel.service
|
|
```
|