Build and distribute software tools with Spack for the EBRAINS Collaboratory Lab containers.
Build and distribute EBRAINS software tools with Spack.
**Quickstart for Notebooks**
- Open a terminal at a running Collaboratory Lab Container and execute the following:
## Introduction
Building and deploying EBRAINS tools to make them available for direct use in the Collaboratory Lab environment is a challenging task, mainly due to the number of tools and the increasing complexity of resolving their dependency conflicts. To efficiently solve this problem, we have implemented a delivery strategy based on [Spack](https://spack.io/), a package manager specifically designed to simplify the installation and management of scientific software (more information [here](https://drive.ebrains.eu/f/73bcfe5acf924cef83cc/)).
Spack is highly customizable and flexible, allowing developers to create their own packages and specify their dependencies and custom build configurations. It supports a wide range of programming languages (Python, R, C, C++, Fortran etc), different hardware architectures and operating systems. All an EBRAINS developer needs to do is create a Spack package (simple description of the build logic of their software). Then Spack automatically handles downloading, building, and installing the entire EBRAINS environment, managing all their dependencies and other requirements.
## Repository
This repository is where the EBRAINS Spack packages are maintained. It contains:
- the EBRAINS [Spack repository](https://spack.readthedocs.io/en/latest/repositories.html), that contains all available EBRAINS Spack packages ([packages/](packages))
- the latest EBRAINS [Spack environment](https://spack.readthedocs.io/en/latest/environments.html)([spack.yaml](spack.yaml)), a list of the specific versions of EBRAINS tools that are part of the software release
- a script ([install_spack_env.sh](install_spack_env.sh)) that can be used to install the latest spack environment on any machine (either install from scratch or update an existing installation)
- CI/CD pipelines configured for (a) testing the installation of new packages and (b) deploying the environment to the EBRAINS Collaboratory Lab.
## Contributing
HBP's developers/component owners that want their EBRAINS tools to be included in the official EBRAINS releases and deployed for direct use from the Lab environment should follow those steps:
- Fork this repository
- Clone the forked repository to local machine (or use the Gitlab Web IDE)
- Create a new Spack package for your tool. For instructions on how to do this, see [the Spack documentation](https://spack.readthedocs.io/en/latest/packaging_guide.html) and the developer's section of [our documentation](https://drive.ebrains.eu/f/73bcfe5acf924cef83cc/). **Add the new package** to the repository, by creating a directory inside [packages/](./packages/) and copying the package recipe there. Also don't forget to **add a spec** to [spack.yaml](spack.yaml)
- Commit the new package and push to a new branch, e.g. `add-packagename`
- Create a Merge Request to merge your changes into the master branch of the original repository
- Check the results of the automated test build job and solve any issues
- Once the tests pass, wait for TC to approve and merge. Once merged, the package will be automatically built and deployed to the integration environment of the Collaboratory Lab (lab-int).
## Installing the EBRAINS official Software release
To install the EBRAINS Spack environment on a new machine, it is recommended to follow exactly the steps from [install_spack_env.sh](install_spack_env.sh), that installs or updates and tests the spack environment defined in this repository. In general, you need to:
Clone this repository. You can use the `ebrains-yy-mm` branches to install the EBRAINS official releases, the `experimental-rel` branch for the experimental release, or the `master` branch for the latest state:
- Then you can start python and import the available tools
- Currently installed:
arbor
neuron
nest
## Gitlab CI/CD Enviromental variables
The following variable(s) must be set up if not or re-configured if tokens expire.
OPENSHIFT_TOKEN: Token to login to OpenShift cluster (with the "gitlab" service account)
OPENSHIFT_DEV_SERVER: The URL of the OpenShift Development cluster needed for deploying software in lab-int environment
BUILD_ENV: The name of the environment to deploy the software of the next commit
OPERATION: The operation to perform on the spack environment (one of the following: testing, create, update, delete)
## Copy spack .yaml files and packages to the Openshift job pod that does the build
The gitlab runner copies the various files needed for the build to the OpenShift job pod.
- It copies the {spack, repo}.yaml files, the create_JupyterLab_kernel.sh script and the packages/ directory
- The runner waits until the job's pod is running to start copying the files
- The pod (built from [tc/ebrains-spack-build-env:latest image](https://docker-registry.ebrains.eu/harbor/projects/8/repositories/ebrains-spack-build-env)) waits until the necessary file(s) has finished copying so that it can continue the build process
## Bulding software binaries with Spack
- The build process is powered by Spack a multi-platform package manager that builds and installs multiple versions and configurations of software.
- A Job (object) in OpenShift is responsible for the build process.
- The gitlab runner starts a new Job that runs on an OpenShift pod that uses the container image developed in [this](https://gitlab.ebrains.eu/akarmas/ebrains-spack-build-env/) repository that holds all the Spack specifics needed for the build process. All the Spack configuration necessary for a successfull build is to be changed from the Spack configuration files that are found in the present repository.
- The OpenShift Job's pod mounts an NFS drive that is also mounted by all Collaboratory Lab containers and performs the entire build process with Spack on that NFS drive and as a result all the installed software is readily available to Collaboratory Lab containers
- A schema of the build process can be found [here](https://drive.ebrains.eu/smart-link/6adcd99f-c088-472e-a596-37ac38869051/)
## Activating software in the Collaboratory Lab containers
- Currently to activate the pre-built simulation tools in the Collaboratory Lab containers refer to **Quickstart** at the beggining of this file
- There are two options: i) for using the simulation tools directly in the notebooks and ii) for using the simulation tools from a terminal in a Collaboratory Lab container
**ToDo: put the necessary activation commands in the startup script of a JupyterLab conatiner spawned in OpenShift to hide all implementation details from the users**
Install:
```
spack install --fresh
```
## Troubleshooting
If you encounter any issues with installing, testing, or using the EBRAINS Spack environment or a specific package, please [open an issue](https://gitlab.ebrains.eu/technical-coordination/project-internal/devops/platform/ebrains-spack-builds/-/issues/new) using the provided templates, or contact the Technical Coordination team directly.
