This service consists of:
- a reverse proxy with caching, listening on port 8000, and exposed at 127.0.0.1:8200 when running the Docker image locally
- the main service, listening on port 8010 and accessed only through the proxy above
This is a simplified request response diagram:
sequenceDiagram
participant User
participant Proxy as Proxy:8000
participant API as API:8010
participant Nexus
User->>+Proxy: GET /circuit
Proxy->>+API: GET /auth
API->>+Nexus: GET /acls
Nexus-->>-API: 200 OK
Note over API: Check permissions
API-->>-Proxy: 200 OK
Proxy->>+API: GET /circuit
API->>+Nexus: GET <resources>
Nexus-->>-API: 200 OK
Note over API: Build response
API-->>-Proxy: 200 OK
Proxy-->>-User: 200 OK
Both the /auth
and /circuit
requests can be independently cached on the proxy.
The API documentation is available at:
- https://cells.sbo.kcp.bbp.epfl.ch/docs for the k8s deployment.
- https://openbluebrain.com/api/circuit/docs for the AWS deployment.
- http://127.0.0.1:8200/docs when running locally in Docker.
To make a release, build and publish the Docker image to the Docker Hub registry, you need to:
- create a release through the GitHub UI (preferred), or
- push a tag to the main branch using git.
The format of the tag should be YYYY.M.N
, where:
YYYY
is the full year (2024, 2025...)M
is the short month, not zero-padded (1, 2 ... 11, 12)N
is any incremental number, not zero-padded (it doesn't need to be the day)
The new Docker image is automatically pushed to Docker Hub as part of the CI pipeline.
-
Mount
/gpfs
if not mounted already:sshfs $USER@bbpv2.epfl.ch:/gpfs /gpfs -o 'ro,allow_other'
-
Build and start the Docker image locally:
make run
-
Assign the nexus token to a variable. You can copy it from the correct instance of Nexus Fusion (on AWS or k8s), or use bbp-workflow-cli (k8s):
NEXUS_TOKEN=$(bbp-workflow -v get-token)
-
Set the Nexus variables depending on the environment and replace
CIRCUIT_ID
with the desired circuit id:-
Nexus on AWS
NEXUS_ENDPOINT="https://openbluebrain.com/api/nexus/v1" NEXUS_BUCKET="bbp/mmb-point-neuron-framework-model" CIRCUIT_ID="https://bbp.epfl.ch/data/bbp/mmb-point-neuron-framework-model/2b29d249-6520-4a98-9586-27ec7803aed2"
-
Nexus on k8s prod
NEXUS_ENDPOINT="https://bbp.epfl.ch/nexus/v1" NEXUS_BUCKET="bbp/mmb-point-neuron-framework-model" CIRCUIT_ID="https://bbp.epfl.ch/data/bbp/mmb-point-neuron-framework-model/2b29d249-6520-4a98-9586-27ec7803aed2"
-
Nexus on k8s staging
NEXUS_ENDPOINT="https://staging.nise.bbp.epfl.ch/nexus/v1" NEXUS_BUCKET="bbp/mmb-point-neuron-framework-model" CIRCUIT_ID="https://bbp.epfl.ch/data/bbp/mmb-point-neuron-framework-model/75a2feb8-2a9a-4f31-b50c-49e098a6c1f4"
-
-
Set correct API endpoint of the service:
-
Cell service on AWS:
API="https://openbluebrain.com/api/circuit"
-
Cell service on k8s:
API="https://cells.sbo.kcp.bbp.epfl.ch"
-
Cell service running locally in Docker:
API="http://127.0.0.1:8200"
-
-
Make a call to the
/version
endpoint to know the version of the deployed service:curl "$API/version"
-
Make a call to the
/circuit/count
endpoint to get the number of neurons:curl -G "$API/circuit/count" \ --data-urlencode "circuit_id=$CIRCUIT_ID" \ -H "nexus-token: $NEXUS_TOKEN" \ -H "nexus-endpoint: $NEXUS_ENDPOINT" \ -H "nexus-bucket: $NEXUS_BUCKET" \ -H "content-type: application/json"
-
Make a call to the
/circuit
endpoint to get the positions of cells:curl -G "$API/circuit?region=581&how=json" \ --data-urlencode "circuit_id=$CIRCUIT_ID" \ -H "nexus-token: $NEXUS_TOKEN" \ -H "nexus-endpoint: $NEXUS_ENDPOINT" \ -H "nexus-bucket: $NEXUS_BUCKET" \ -H "content-type: application/json" \ -o output.json
The development of this software was supported by funding to the Blue Brain Project, a research center of the École polytechnique fédérale de Lausanne (EPFL), from the Swiss government’s ETH Board of the Swiss Federal Institutes of Technology.
For license see LICENSE.txt.
Copyright (c) 2022-2024 Blue Brain Project/EPFL