Configuration#

JupyterHub configuration#

Create configuration file:

$  pipenv run jupyterhub --generate-config
Writing default config to: jupyterhub_config.py

System Service for JupyterHub#

Determine the Python virtual environment:

$ cd ~/jupyter-tutorial
$ pipenv --venv
/srv/jupyter/.local/share/virtualenvs/jupyter-tutorial-aFv4x91W

Configure the absolute path to jupyterhub-singleuser in the jupyterhub_config.py file:

c.Spawner.cmd = ['/srv/jupyter/.local/share/virtualenvs/jupyter-tutorial-aFv4x91/bin/jupyterhub-singleuser']

Add a new systemd unit file /etc/systemd/system/jupyterhub.service with the command:

$ sudo systemctl edit --force --full jupyterhub.service

Add your corresponding Python environment.

[Unit]
Description=Jupyterhub

[Service]
User=root
Environment="PATH=/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/srv/jupyter/.local/share/virtualenvs/jupyterhub-aFv4x91W/bin"
ExecStart=/srv/jupyter/.local/share/virtualenvs/jupyterhub-aFv4x91W/bin/jupyterhub -f /srv/jupyter/jupyterhub_env/jupyterhub_config.py

[Install]
WantedBy=multi-user.target

Loading the configuration with:
```
$ sudo systemctl daemon-reload
```

The JupyterHub can be managed with:

$ sudo systemctl <start|stop|status> jupyterhub

To ensure that the service is also loaded during a system start, the following is called:

$ sudo systemctl enable jupyterhub.service
Created symlink /etc/systemd/system/multi-user.target.wants/jupyterhub.service → /etc/systemd/system/jupyterhub.service.

To be able to use the jupyterhub-singleuser and start your own server, the ix users must be entered in the jupyter group, for example with usermod -aG jupyter VEIT.

Since JupyterHub includes authentication and allows the execution of any code, it should not be executed without SSL (HTTPS). To do this, an official, trustworthy SSL certificate must be created. After you have received and installed a key and a certificate, you don’t configure the JupyterHub itself, but the upstream Apache web server.

For this purpose, the additional modules are first activated with
```
# a2enmod ssl rewrite proxy proxy_http proxy_wstunnel
```

Then the VirtualHost can be configured in /etc/apache2/sites-available/jupyter.cusy.io.conf

# redirect HTTP to HTTPS
<VirtualHost 172.31.50.170:80>
    ServerName jupyter.cusy.io
    ServerAdmin webmaster@cusy.io

    ErrorLog ${APACHE_LOG_DIR}/jupyter.cusy.io_error.log
    CustomLog ${APACHE_LOG_DIR}/jupyter.cusy.io_access.log combined

    Redirect / https://jupyter.cusy.io/
</VirtualHost>

<VirtualHost 172.31.50.170:443>
  ServerName jupyter.cusy.io
  ServerAdmin webmaster@cusy.io

  # configure SSL
  SSLEngine On
  SSLCertificateFile /etc/ssl/certs/jupyter.cusy.io_cert.pem
  SSLCertificateKeyFile /etc/ssl/private/jupyter.cusy.io_sec_key.pem
  # for an up-to-date SSL configuration see e.g.
  # https://ssl-config.mozilla.org/

  # Use RewriteEngine to handle websocket connection upgrades
  RewriteEngine On
  RewriteCond %{HTTP:Connection} Upgrade [NC]
  RewriteCond %{HTTP:Upgrade} websocket [NC]
  RewriteRule /(.*) ws://127.0.0.1:8000/$1 [P,L]

  <Location "/">
    # preserve Host header to avoid cross-origin problems
    ProxyPreserveHost on
    # proxy to JupyterHub
    ProxyPass         http://127.0.0.1:8000/
    ProxyPassReverse  http://127.0.0.1:8000/
  </Location>

  ErrorLog ${APACHE_LOG_DIR}/jupyter.cusy.io_error.log
  CustomLog ${APACHE_LOG_DIR}/jupyter.cusy.io_access.log combined
</VirtualHost>

This VirtualHost is activated with
```
# a2ensite jupyter.cusy.io.conf
```

Finally, the status of the Apache web server is checked with

# systemctl status apache2
● apache2.service - The Apache HTTP Server
   Loaded: loaded (/lib/systemd/system/apache2.service; enabled; vendor preset: enabled)
   Active: active (running) (Result: exit-code) since Mon 2019-03-25 16:50:26 CET; 1 day 22h ago
  Process: 31773 ExecReload=/usr/sbin/apachectl graceful (code=exited, status=0/SUCCESS)
 Main PID: 20273 (apache2)
    Tasks: 55 (limit: 4915)
   CGroup: /system.slice/apache2.service
           ├─20273 /usr/sbin/apache2 -k start
           ├─31779 /usr/sbin/apache2 -k start
           └─31780 /usr/sbin/apache2 -k start

Mar 27 06:25:01 jupyter.cusy.io systemd[1]: Reloaded The Apache HTTP Server.

Proxy authentication token#

The hub authenticates its requests to the proxy using a secret token that the hub and proxy agree on. Usually, the proxy authentication token does not need to be set, as the hub itself generates a random key. This means that the proxy has to be restarted every time unless the proxy is a subprocess of the hub.

Alternatively, the value can e.g. can be generated with
```
$ openssl rand -hex 32
```

It can then be entered in the configuration file, for example with

c.JupyterHub.proxy_auth_token = '18a0335b7c2e7edeaf7466894a32bea8d1c3cff4b07860298dbe353ecb179fc6'

Configuration#

JupyterHub configuration#

System Service for JupyterHub#

Cookie Secret#

Proxy authentication token#