Initial setup

Installation

Clone the starting repository

Clone the brainflex-node repository:

git clone https://github.com/neurodatascience/brainflex-node
cd brainflex-node

Create virtual environment and install Python dependencies

With uv

uv venv --python 3.14
source .venv/bin/activate
uv pip install -r requirements.txt

With venv

Make sure your Python version is between 3.11 and 3.14 inclusive.

python3 -m venv .venv --prompt brainflex-node
source .venv/bin/activate
pip install -r requirements.txt

With conda

conda create --name brainflex-node python=3.14
conda activate brainflex-node
pip install -r requirements.txt

Verify installation

The above step installs three packages/tools:

  1. bagel: Neurobagel CLI

  2. nipoppy: Nipoppy CLI

  3. brainflex: Custom helper tool for this project

You can verify that they were installed successfully by running <TOOL_NAME> --help, where <TOOL_NAME> is one of bagel, nipoppy, and brainflex. This should print information about the CLI commands and options.

Initial survey

Answer a short survey about your prior experience with Nipoppy, Neurobagel and Fed-BioMed:

brainflex initial-survey

Node configuration

Attention

config.env and .env are Git-ignored and should never be shared.

config.env file

Put the config.env file that was shared with you in the vpn_config/ directory:

mv <PATH_TO_CONFIG_ENV> vpn_config/config.env

.env file

Create a .env file from the provided template:

cp .env.example .env

Edit .env and set:

  • FBM_NODE_NAME to the value of FEDBIOMED_NODEID in the config.env file that was shared with you

  • CONTAINER_UID and CONTAINER_GID to the output of id -u and id -g, respectively

Example .env file content

#
# docker-compose.yml variables
# Copy to `.env` and edit as needed
#

# Fed-BioMed version of the node image
# Must be the same version as the researcher and the VPN server
FBM_CONTAINER_VERSION_TAG=6.4.1

# Unique ID for this instance, among all the instances deployed on this machine
# (used in container names)
FBM_CONTAINER_INSTANCE_ID=default

# Fed-BioMed node name, as shown to the researcher
FBM_NODE_NAME=mcgill

# Host user and group owning the files in `fbm-node`
# Set to the output of `id -u` and `id -g`. If unset, files are owned by UID/GID 2101
CONTAINER_UID=1002
CONTAINER_GID=1001

# Relative or absolute path to the Nipoppy study associated with this node
NIPOPPY_ROOT=./nipoppy_study

# Researcher address on the VPN (Fed-BioMed VPN defaults)
#FBM_RESEARCHER_IP=10.222.0.2
#FBM_RESEARCHER_PORT=50051

# Options passed to `fedbiomed node start`, eg `--gpu`
#FBM_NODE_START_OPTIONS=

# Node security settings (Fed-BioMed defaults shown)
FBM_SECURITY_FORCE_SECURE_AGGREGATION=True
FBM_SECURITY_TRAINING_PLAN_APPROVAL=True
FBM_SECURITY_ALLOW_DEFAULT_TRAINING_PLANS=False
FBM_SECURITY_ALLOW_PREPROC=True
FBM_SECURITY_ALLOW_FEDERATED_ANALYTICS=True

Data download

Download the OpenNeuro dataset assigned to your site, replacing <DATASET_ID> with its ID (beginning with ds):

brainflex get-data <DATASET_ID>

This creates a minimal Nipoppy study in nipoppy_study that contains all the data needed for the federated learning experiment.