Loading…
Loading…
A practical overview for an institution considering running a Sub-regional Hub, National Hub, or Spoke — a node — in the African DSI DataBank federation. See Governance for how node admission and administrative decisions work. Requesting an operator account (Apply) and registering a brand-new node's existence (Register node) are two separate steps, but not independent ones — see "Getting a node running" below for the order that actually works.
Stay up to date: new features, action needed and maintenance are announced in Updates for node operators, which every node also shows on its own Updates page.
This page is an overview. The full handbook, with every setting and command, comes with the node software itself: docs/NODE_OPERATOR_HANDBOOK.md in your node's files, updated with each release.
Every tier — Sub-regional Hub, National Hub, Spoke — runs the same underlying software, configured differently. Your node holds your own institution's data as the source of truth, and decides for itself whether and what to sync upward to the rest of the federation.
There is no fixed hardware requirement — the node software itself is small. What actually drives sizing is your own data:
Every release supports both ways; they install the same software.
node.env yourself) is for a shared server or an unusual setup: another web server already using ports 80 and 443 (your own nginx, Apache or Caddy in front), a node under a path on an existing website (NODE_BASE_PATH), more than one node on one server, or anything else the easy way doesn't fit.A node set up either way is the same afterwards: it updates the same way, and Reconnect on Tier status fetches fresh credentials for both.
--native for the system package), or use On a new cloud server for a start-up script. It checks the server and the release's signature, then prints a setup code.The install command needs ports 80 and 443 free and won't replace a configured node, so put an earlier attempt aside first. Its data is kept unless you delete it.
docker compose … -p <your-project> command you used, with down instead of up -d (add -v only to delete the data too), then rename that folder's node.env to node.env.old.for unit in backend web sync proxy; do sudo systemctl disable --now "africandsidatabank-node-$unit"; done (a unit that doesn't exist just reports so), then sudo apt remove africandsidatabank-node (or dnf remove) for a package, and sudo mv /etc/africandsidatabank/node.env /etc/africandsidatabank/node.env.old. Data stays under /var/lib/africandsidatabank/.sudo ss -ltnp '( sport = :80 or sport = :443 )' should list nothing..deb or .rpm), or local processes for development. Your node can have its own host name or live under a path on an existing site (for example https://example.org/AfricanDSIDataBank/, set with NODE_BASE_PATH).node.env, never by editing the code. Updates replace the code folders, so every adjustment is a setting in node.env or, for Docker additions, your own compose file kept outside the deploy/ folder.This project's own source code is private, and you don't need git access to it — every release (whichever of the three install options above you pick) is a set of plain, downloadable files, gated to logged-in, approved node operators. Two independent checks are made against every download before it's ever trusted: its manifest's own GPG signature is verified against this project's published release-signing key, and the file's own SHA-256 checksum is then verified against that now-trusted manifest. Either check failing means the file is rejected outright.
The release-signing key's fingerprint (ed25519, sign-only, never expires) — published here specifically so you have somewhere independent of the download itself to cross-check against, the standard "trust on first use" step this signing scheme depends on:
D7B5 B8A7 58C7 2D04 B778 1F36 5D29 8472 953F 3E09
A copy-pasteable first-install example (only the password prompt is ever typed — it's read straight into a shell variable, never echoed or logged):
HUB_URL="https://hub.africandsidatabank.africa"
# 1. Find the current release's id
curl -sS "$HUB_URL/api/v1/node-releases/latest"
# -> {"id": 3, "version": "0.1.2", ...} - note the "id"
# 2. Log in with your own central-login account
read -p "Username: " NODE_USER
read -sp "Password: " NODE_PASS; echo
JWT=$(curl -sS -X POST "$HUB_URL/api/v1/accounts/login" \
-H "Content-Type: application/json" \
-d "{\"username\": \"$NODE_USER\", \"password\": \"$NODE_PASS\"}" \
| python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
# 3. Download the manifest, its signature, and the gated tarball (use the
# id from step 1; swap "tarball" for "deb"/"rpm" if you'd rather use a
# package)
RELEASE_ID=3
curl -sS -o SHA256SUMS.txt "$HUB_URL/api/v1/node-releases/$RELEASE_ID/checksums-manifest"
curl -sS -o SHA256SUMS.txt.asc "$HUB_URL/api/v1/node-releases/$RELEASE_ID/checksums-manifest.asc"
curl -sS -H "Authorization: Bearer $JWT" -o node-release.tar.gz \
"$HUB_URL/api/v1/node-releases/$RELEASE_ID/download/tarball"
# 4. Extract ONLY deploy/ first, then cross-check the fingerprint it
# reports against the value published above, before trusting anything
# further
tar xzf node-release.tar.gz ./deploy
gpg --show-keys --with-fingerprint ./deploy/RELEASE_SIGNING_PUBLIC_KEY.asc
# 5. Once the fingerprint genuinely matches, verify the whole download -
# it exits non-zero on any failure, and only prints what to run next
# (extract the rest, then install) once both checks genuinely pass
./deploy/verify-node-release.sh node-release.tar.gzPrefer not to run curl commands by hand? Once you're approved and logged in, your own node's "Tier status" page (see "Upgrading" below) can download and verify a release for you the same way — the manual walkthrough above is the one thing worth doing yourself at least once, so you've seen the fingerprint check with your own eyes before trusting it to run unattended.
Normally your parent node and the Continental Hub each fetch your node's changes on a schedule. If they can't reach your node (often because an institutional firewall blocks unfamiliar servers), your node can send its changes instead: to the Continental Hub, to its parent, or to both. You choose.
Pushed changes go through exactly the same checks as fetched ones, and push only replaces sync: transfers and compute requests still need the Hub to reach your node.
From node 0.5.11, the Outreach pack panel on your node's Tier status page gives you the DataBank's outreach materials made for your node, in the same three tiers as the DataBank's own: an A3 poster for policy makers and executives, an A4 fact sheet for informed audiences, and slides for academics and researchers.
Workshop materials you make about your own data can be shared publicly on the Hub's Training materials page (published once the Continental Admin approves them).
In addition to uploading files through the browser, your node can use data files that already sit on its server. Your administrator lists the folders it may use (NODE_DATA_ROOTS in node.env). Then every upload form offers "A file already on this server", with a folder browser, and the node's Files on this server page imports many records at once from a CSV, for any data type.
For each file you choose either to copy it into the node, like an upload, or to serve it in place, with no copy. A file served in place must stay where it is, unchanged: the node checks it regularly and stops serving it if it has moved or changed, until you re-check or re-register it. Records made either way are ordinary records: they sync, can be transferred and are citable like any other.
From 0.5.5 a derived analysis result can have an optional title, such as its sample accession. Set it in the form, as a title column in a CSV, or by editing a result you've already registered. Your node's Derived Analysis page and the Hub's both show the newest results first, with Load more and a search box (title, file name, tool, analysis type, species; on the Hub also the citable ID). Every card has a Download button, and files save under their own names.
Nothing is deleted outright: removing a result is a retraction. From 0.5.6 you retract results your node created yourself, on your node, one at a time or every result matching a search, with a reason and no approval needed. They leave every list at once, and the parent node and the Hub follow with the next sync; the citable ID keeps resolving to the retraction notice, and you can undo a retraction. From 0.5.7 the same works for every data type, on the node's Operations → Retractions page; records made from a retracted one (a sample's profiles, a genome's proteins) go with it. "Import from server" takes up to 5,000 rows per CSV, so split larger collections.
From 0.5.0 your node can help train a model across nodes without its data leaving your server. The Continental Admin starts a training run and invites nodes; you accept or decline each run on your node's Federated training page, which shows how many of your records it would use. Your node then trains the run's model on its own records (public ones by default, never embargoed ones, never records relayed from other nodes) and sends the Hub only the model's weights and a few summary numbers. It connects out to the Hub itself, so it works behind a firewall.
Training runs in containers started by your node's container runner, with no network and fixed limits, using only images pinned to an exact version by the Hub (from 0.5.1 usually served by the Hub itself, only to nodes taking part in the run). It's off until you switch it on (NODE_FEDERATED_TRAINING, plus the runner); the full handbook explains how, including GPUs. The finished model is published on the Hub as a citable result listing which nodes contributed.
You don't have to run this platform's own reference software. The federation's node protocol is a documented, versioned contract — if your institution already runs its own bioinformatics infrastructure, you can implement that contract directly against your own systems instead of standing up a second stack. The minimum to be a working node is small; everything beyond that is optional and degrades gracefully if you don't implement it — that one feature simply doesn't work for your node, nothing else is affected. The Continental Hub will label your node by its own reported software name rather than assuming it runs the reference implementation — purely informational, never a gate on anything.
Your node's database (metadata) and object storage (actual file bytes) are two separate things and both need regular backups — losing either loses real data your node is the source of truth for. Content checksums, computed when a file reaches the Hub, are one way to later verify a restored copy matches what was originally captured. Files your node serves in place from its own folders aren't in its storage, so back those folders up as well.
Database schema changes apply automatically on startup — in practice, get a newer version and restart the service, and the schema updates itself before the software starts serving requests. Take a backup before any version upgrade regardless.
A banner tells you when a newer version is available; it never applies anything on its own, and it turns amber for a security release and red once an update has waited too long. Your node's Tier status page then offers Update now, Update in 3 hours or Defer. You can also turn on automatic updates there (off by default), and your node then checks about every 15 minutes and installs a new version itself, after verifying it.
Before updating, the updater checks that nobody has edited the node's code. If someone has, it stops and lists the changed files rather than overwrite them. It backs up the current code before every update and never touches your node.env.
Every install type updates itself, including .deb/.rpm packages (from 0.5.13): the updater installs the verified new package with the package manager and, if the update fails, puts back the version you were running. Your firewall doesn't matter: your node contacts the Hub, never the other way round, so a node that syncs by push can update automatically too. The Updater box on Tier status shows when it last checked and what happened, so you can see that it's working.
0.12.0 is a security update and gives every node its own credentials. After updating, on Tier status:
FEDERATION_ROOT_TOKEN from node.env, then rebuild as usual. It isn't needed any more.Every DSI record your node syncs upward gets a real, durable citable id the moment it reaches the Hub, with a one-click citation string and BibTeX export on its own citation page — see Terms of Use's citation policy. Your node's own real contribution counts (records, views, downloads) are also visible, publicly and by name, on the Hub's Participation dashboard.
See also: Governance, API guide.