Shanoir-NG (Next Generation) is a software that helps neuroimaging analysis researchers, radiologists, and MRI operators to organize and share neuroimaging datasets.
GitHub is a tool for developers if you are seeking information at a user level view please visit http://shanoir.org.
Shanoir-NG is a complete technological remake of the first version of the Shanoir application, maintaining the key concepts of Shanoir, enhancing the functionalities and the user interface and providing a great flexibility for further improvements.
Shanoir-NG is copyrighted by Inria and is now open source under the GNU General Public License v3.0. See the LICENCE file at the root of this project. If you want to contribute, please see the following page : Contribution Workflow.
The latest stable version of Shanoir-NG is on the branch "master".
The latest dev version of Shanoir-NG is on "develop" (if mature -> merged into master)
You can find the installation instructions for "master" branch below.
Shanoir NG is still in the developement phase. While many functionalities work well, some are not developed yet and some might be unstable. Also It still misses production features like database backup.
A few .env files in the docker-compose layer contain clear Keycloak password. Please choose your own password (check Keycloak password format policy first).
Many thanks to all these giants, on their shoulders we are standing to develop Shanoir-NG !
You can easily connect and investigate the REST-interface of Shanoir-NG using Swagger3. Depending on your server domain just call (e.g. for Neurinfo server):
Clone the shanoir-ng repository, the shanoir-downloader/ folder will be empty ; two commands must be run to get the code:
git submodule init
to initialize your local configuration filegit submodule update
to fetch all the data from shanoir and check out the appropriate commit listed in shanoir_downloader
Then the shanoir-downloader project can be simply managed as a normal git repo (as if it were a separated project) ; meaning that once your are in the shanoir-downloader/ folder, you can just git pull
to get the latest changes, and commit some changes.
Install Docker Desktop
Install Java 21
Install Maven
Install NodeJS (+npm)
Add a repository to maven (your_path_to_apache_folder\apache\conf\settings.xml or mvn help:effective-settings to check path) :
Configure git to change end of line caracters to windows' instead of linux' : git config --global core.autocrlf input
Add this line to C:\Windows\System32\drivers\etc\hosts : 127.0.0.1 shanoir-ng-nginx viewer
Fork GitHub project
Clone
Edit .env file and set SHANOIR_MIGRATION=init
Run "mvn clean install -DskipTests" in shanoir-ng/shanoir-ng-parent/ folder
Run docker-compose up --build in shanoir-ng/
Load data manually from Docker Desktop :
Shanoir : https://shanoir-ng-nginx/shanoir-ng/home
Keycloak : http://localhost:8080/auth/admin/master/console/#/realms/shanoir-ng/roles
If you want to login, please configure a user in Keycloak :
Please note, that the MS Users does for security reasons not publicly expose his REST-interface.
To build and deploy Shanoir, you will need:
The installation of Shanoir NG happens in three steps :
The TL;DR section gives the minimal for bootstrapping a development environment. The following sections give detailed informations about each step.
The default docker-compose configuration is well-suited for a development environment. Each microservice is hosted in a separate container and the application data are stored in named volumes.
Before deploying, some configuration is required:
127.0.0.1 shanoir-ng-nginx viewer
The bootstrap.sh script automates the build and the deployment of shanoir.
WARNING: this script is destructive (as it will wipe out the external volumes configured in the docker-compose.yml). It is not recommended to use on a production host.
To deploy shanoir from scratch on a development machine you can just launch the following command and have a coffee.
./bootstrap.sh --clean
Once the bootstrap is complete, go on to the FIRST RUN section to create the initial users.
The build consists of two stages: build the microservices and build the docker images.
In the source tree, each microservice is located in a separate shanoir-ng-*/
directory containing a maven project. shanoir-ng-parent
is a meta-project that
includes all the other projects. The contextes of the docker images are located
in the docker-compose/*/
directories.
Procedure:
Download or git clone the shanoir-ng code. The master
branch should be the
most stable while develop
will contain the newests functionalities if you
are interested in testing thoses.
Execute the Maven build on the parent project with the following commands:
cd shanoir-ng-parent/ && mvn install
The build creates all .jar and .js executable files and stores a copy into the docker-compose/ folder to be used for building the docker images
Build the docker images:
docker-compose build
Shanoir is configured with environment variables. It is mostly handled with a a
set of facade variables named SHANOIR_*
(which cover the most typical
setups).
Name | Value | Description |
---|---|---|
SHANOIR_URL_HOST |
hostname | hostname where shanoir is reachable |
SHANOIR_URL_SCHEME |
http\|https |
https (over TLS), http (plain text, NOT RECOMMENDED) |
SHANOIR_SMTP_HOST |
hostname | SMTP relay for outgoing e-mails |
SHANOIR_ADMIN_EMAIL |
e-mail address | contact address of the administrator (for outgoing e-mails) |
SHANOIR_ADMIN_NAME |
name | name of the administrator (for outgoing e-mails) |
SHANOIR_PREFIX |
slug (optional) | prefix for container names (needed if you deploy multiple shanoir instances on the same host) |
SHANOIR_X_FORWARDED |
generate\|trust |
configures whether the nginx container generates the X-Forwarded-* HTTP headers (if running stand-alone) or trusts the existing headers (if located behind another reverse-proxy) |
SHANOIR_CERTIFICATE |
auto\|manual |
auto-generates a self-signed TLS certificate (NOT RECOMMENDED) or use a manually installed certificate |
SHANOIR_MIGRATION |
auto\|init\|never\|manual\|export\|import |
Normal runs should use auto in development and never in production. Other values are for controlling deployment and migrations (see below). |
SHANOIR_KEYCLOAK_USER SHANOIR_KEYCLOAK_PASSWORD |
username/password | Keycloak admin account used by shanoir for managing user accounts |
SHANOIR_VIEWER_OHIF_URL_SCHEME |
http\|https |
https (over TLS), http (plain text, NOT RECOMMENDED) |
SHANOIR_VIEWER_OHIF_URL_HOST |
hostname | hostname where the OHFI-Viewer is reachable |
Notes
SHANOIR_URL_HOST
can be resolved from the
clients using shanoir (the users) and from each microservice (running in the
containers)
127.0.0.1 shanoir-ng-nginx viewer
SHANOIR_URL_HOST
(in the default setup, they both use:
shanoir-ng-nginx
)docker-compose up -d
). However if the changes also
affect the keycloak container, then you will also need to re-deploy the
shanoir-ng realm (see below).ensure all containers are stopped and all volumes are destroyed (CAUTION: this destroys all external volumes defined in docker-compose.yml)
fig down -v
deploy the database containers and wait until they are ready to accept incoming connections
docker-compose up -d database keycloak-database
initialise the keycloak container, then start it
docker-compose run --rm -e SHANOIR_MIGRATION=init keycloak
docker-compose up -d keycloak
initialise each microservice
for ms in users studies datasets import preclinical ; do
docker-compose run --rm -e SHANOIR_MIGRATION=init "$ms"
done
start the remaining containers
docker-compose up -d
New user accounts need to be validated by a shanoir admin. However, on the first run, there is not admin account so you will need to create it on the keycloak server directly:
SHANOIR_KEYCLOAK_USER
/SHANOIR_KEYCLOAK_PASSWORD' (default is
admin/
&a1A&a1A`)ROLE_ADMIN
). By
default, new user accounts are created in Keycloak by the users microservice
with temporary passwords, you may reset the password in keycloak's admin
interface and receive the new password is by e-mail. In development, if you
do hot have a configured SMTP relay, then you may choose to overide the
password manually and set Temporary password: No
to make it persistent.
Go to the "Attributes" tab of your User page and create a new attribute "userId" and set the value with a random number not taken by another user.Access to the backup PACS dcm4chee 5 arc-light: http://localhost:8081/dcm4chee-arc/ui2/
This installation uses Docker named volumes, find more here to handle your local data: https://docs.docker.com/storage/volumes/
TODO