# Installation

It's recommended to install the offline calibration (pycalibration)
package on maxwell, using the anaconda/3 environment.

The following instructions clone from the EuXFEL GitLab instance using
SSH remote URLs, this assumes that you have set up SSH keys for use with
GitLab already. If you have not then read the appendix section on [SSH
Key Setup for GitLab](#ssh-key-setup-for-gitlab) for instructions on how
to do this.

## Installation using python virtual environment - recommended

`pycalibration` uses Python 3.8. Currently, the default
python installation on Maxwell is still Python 3.6.8, so Python 3.8
needs to be loaded from a different location.

One option is to use the Maxwell Spack installation, running `module
load maxwell` will activate the test Spack instance from
DESY, then you can use `module load
python-3.8.6-gcc-10.2.0-622qtxd` to Python 3.8. Note that
this Spack instance is currently a trial phase and may not be stable.

Another option is to use `pyenv`, we provide a pyenv
installation at `/gpfs/exfel/sw/calsoft/.pyenv` which we use
to manage different versions of python. This can be activated with
`source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate`

A quick setup would be:

1.  `source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate`
2.  `git clone ssh://git@git.xfel.eu:10022/detectors/pycalibration.git && cd pycalibration` -
    clone the offline calibration package from EuXFEL GitLab
3.  `pyenv shell 3.8.18` - load required version of python
4.  `python3 -m venv .venv` - create the virtual environment
5.  `source .venv/bin/activate` - activate the virtual environment
6.  `python3 -m pip install --upgrade pip` - upgrade version of pip
7.  `python3 -m pip install .` - install the pycalibration package (add
    `-e` flag for editable development installation)

Copy/paste script:

```bash
source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate
git clone ssh://git@git.xfel.eu:10022/detectors/pycalibration.git
cd pycalibration
pyenv shell 3.8.18
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install .  # `-e` flag for editable install, e.g. `pip install -e .`
```

## Creating an ipython kernel for virtual environments

To create an ipython kernel with pycalibration available you should (if
using a venv) activate the virtual environment first, and then run:

```bash
python3 -m pip install ipykernel  # If not using a venv add `--user` flag
python3 -m ipykernel install --user --name pycalibration --display-name "pycalibration"  # If not using a venv pick different name
```

This can be useful for Jupyter notebook tools as [max-jhub documentation](https://rtd.xfel.eu/docs/data-analysis-user-documentation/en/latest/jhub/)([max-jhub](https://max-jhub.desy.de/hub/login))

## SSH Key Setup for GitLab

It is highly recommended to setup SSH keys for access to GitLab as this
simplifies the setup process for all of our internal software present on
GitLab.

To set up the keys:

1.  Connect to Maxwell
2.  Generate a new keypair with `ssh-keygen -o -a 100 -t ed25519`, you
    can either leave this in the default location (`~/.ssh/id_ed25519`)
    or place it into a separate directory to make management of keys
    easier if you already have multiple ones. If you are using a
    password for your keys please check this page to learn how to manage
    them:
    <https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent>
3.  Add the public key (`id_ed25519.pub`) to your account on GitLab:
    <https://git.xfel.eu/gitlab/profile/keys>
4.  Add the following to your `~/.ssh/config` file

```bash
# Special flags for gitlab over SSH
Host git.xfel.eu
    User git
    Port 10022
    ForwardX11 no
    IdentityFile ~/.ssh/id_ed25519
```

Once this is done you can clone repositories you have access to from
GitLab without having to enter your password each time. As
`pycalibration` requirements are installed from SSH remote URLs having
SSH keys set up is a requirement for installing pycalibration.