magic-lantern/jupyterhub_setup.md

## jupyterhub_setup.md

      
    Raw
  

              jupyterhub_setup.md
            
          
    JupyterHub Setup

System Setup

Setup Users/Groups/paths

sudo addgroup pythonusers
sudo gpasswd -M sethr,rebullm,tellb,dewittp pythonusers
sudo mkdir /opt/miniconda3
sudo chown -R me:pythonusers /opt/miniconda3
cd /opt
# this should make it so all environments have correct rights by default
sudo chmod g+s ./miniconda3
sudo chmod ug+w ./miniconda3

Download required files

Download Mini Anaconda - as of this writing, current Linux version is:
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
sha256sum ./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
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.
Note: channel_priority strict helps to prevent older versions of some packages being pulled from main/default instead of conda-forge.
conda config --add channels conda-forge
conda config --set channel_priority strict
conda create -n jupyterhub python=3.11
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 altair bokeh dask datashader hvplot ipympl ipywidgets jupyter-resource-usage jupyterhub jupyterlab jupytext matplotlib nb_conda notebook pandas polars seaborn
conda install -c plotly plotly dash
Jupyterhub

Test to make sure jupyterhub works
jupyterhub -h
configurable-http-proxy -h
jupyterhub
sudo mkdir /etc/jupyterhub
sudo /opt/miniconda3/bin/jupyterhub --generate-config -f /etc/jupyterhub/jupyterhub_config.py

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

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 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/myserver.my.domain.key -out /etc/ssl/certs/myserver.my.domain.crt

Answers I provided to questions:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:State
Locality Name (eg, city) []:City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:University of Cool
Organizational Unit Name (eg, section) []:Department of Biomedical Informatics
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-the-hard-way/blob/HEAD/docs/installation-guide-hard.md
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 enable jupyterhub.service
sudo systemctl start jupyterhub
sudo systemctl enable jupyterhub

JupyterHub Configuration

/etc/jupyterhub/jupyterhub_config.py
diff jupyterhub_config.py jupyterhub_config.orig
280a281
> c.JupyterHub.cookie_secret_file = '/etc/jupyterhub/jupyterhub_cookie_secret'
808a810
> c.JupyterHub.ssl_cert = '/etc/ssl/certs/myserver.my.domain.crt'
814a817
> c.JupyterHub.ssl_key = '/etc/ssl/private/myserver.my.domain.key'