magic-lantern/jupyterhub_setup.md

## jupyterhub_setup.md

      
    Raw
  

              jupyterhub_setup.md
            
          
    JupyterHub Setup

System Setup

New requirement - npm proxy: https://jupyterhub.readthedocs.io/en/stable/quickstart.html#installation
npm install -g configurable-http-proxy
Download Mini Anaconda - as of this writing, current Linux version is:
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
Miniconda installs only the items you need so it better suited to a server environment.
Install to /opt/miniconda3
sudo mkdir /opt/miniconda3
sudo chown -R me:pythonusers /opt/miniconda3
chmod +x ./Miniconda3-latest-Linux-x86_64.sh
./Miniconda3-latest-Linux-x86_64.sh -u # -u option means to install to already created directory

When prompted, install to /opt/miniconda3 then continue on by adding additional packages
Conda environment

Python version can be adjusted based on requirements and current version of Python available.
conda config --add channels conda-forge
conda config --set channel_priority strict
conda create -n jupyterhub python=3.9
conda activate jupyterhub
# note that many of these packages are recommended to install from conda-forge, but may be available in regular default repo
conda install -c conda-forge jupytext jupyterhub altair vega_datasets ipympl jupyterlab seaborn nb_conda dash jupyter-resource-usage
sudo mkdir /etc/jupyterhub
sudo /opt/miniconda3/bin/jupyterhub --generate-config -f /etc/jupyterhub/jupyterhub_config.py
Note: channel_priority strict helps to prevent older versions of some packages being pulled from main/default instead of conda-forge.
If the last command fails, e.g.,
$ sudo /opt/miniconda3/bin/jupyterhub --generate-config -f /etc/jupyterhub/jupyterhub_config.py
ERROR: Failed to find specified config file: /etc/jupyterhub/jupyterhub_config.py
Then check this github issue: jupyterhub/jupyterhub#2906
Workaround:
cd /etc/jupyterhub
sudo /opt/miniconda3/bin/jupyterhub --generate-config
Conda installs a new pager that can cause problems with many command line tools. Delete it:
sudo rm /opt/miniconda3/bin/pager

Lastly, change permissions so others can use this Anaconda installation if they so desire.
sudo chown -R me:pythonusers /opt/miniconda3

Conda child environment

Any conda environment that you want to be able to use via JupyterHub needs to have the ipykernel package installed.
Follow this pattern:
# other environment requirements?
conda create -n mynewenv python=3.9
conda activate mynewenv
# install what ever packages you need
# if any jupyter environment has nb_conda installed then running this next
# line will make this new environment show up in jupyterhub
conda install ipykernel
Note: When searching stackoverflow or other websites, people often mention a few steps that are NOT required. Specifically, you do not need to:

run ipython kernel install...
jupyter kernelspec list is not conda kernel aware (so don't try to use it for troubleshooting)
no need for files to be present in ~/.local/share/jupyter/kernels

JupyterHub SSL configuration

JupyterHub in https mode requires an SSL certificate. Generate one using this (or just re-use an existing self-signed certificate):
sudo openssl req -x509 -out myserver.my.domain.crt -keyout myserver.my.domain.key \
  -newkey rsa:2048 -nodes -days 365 -sha256 \
  -subj '/CN=myserver.my.domain' -extensions EXT -config <( \
   printf "[dn]\nCN=myserver.my.domain\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:myserver.my.domain\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

Then copy or symlink files to:

/etc/jupyterhub/myserver.my.domain.key
/etc/jupyterhub/myserver.my.domain.crt

Answers I provided to questions:
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Colorado
Locality Name (eg, city) []:Aurora
Organization Name (eg, company) [Internet Widgits Pty Ltd]:University of Cool
Organizational Unit Name (eg, section) []:Data Science to Patient Value
Common Name (e.g. server FQDN or YOUR name) []:myserver.my.domain
Email Address []:me@cool.edu

JupyterHub as a system service

https://github.com/jupyterhub/jupyterhub/wiki/Run-jupyterhub-as-a-system-service
Create service file /etc/systemd/system/jupyterhub.service
[Unit]
Description=Jupyterhub
After=syslog.target network.target

[Service]
User=root
Environment="PATH=/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/opt/miniconda3/condabin:/opt/miniconda3/envs/jupyterhub/bin"
ExecStart=/opt/miniconda3/envs/jupyterhub/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py

[Install]
WantedBy=multi-user.target

Then run the following to start jupyterhub and to make it run at boot:
sudo systemctl daemon-reload
sudo systemctl start jupyterhub
sudo systemctl enable jupyterhub

JupyterHub Configuration

.jupyter/jupyter_notebook_config.py file (generate a Jupyter config, if you don't have one yet, with jupyter notebook --generate-config
$ diff ./jupyterhub_config_new.py ./jupyterhub_config_new.original
165d164
< c.JupyterHub.cookie_secret_file = '/etc/jupyterhub/jupyterhub_cookie_secret'
451d449
< c.JupyterHub.ssl_cert = '/etc/jupyterlab/myserver.my.domain.crt'
457d454
< c.JupyterHub.ssl_key = '/etc/jupyterlab/myserver.my.domain.key'
622d618
< c.Spawner.default_url = '/lab'