Administrators are responsible for configuring, securing, and maintaining JupyterHub to ensure reliable and performant operation.

Resource management

The JupyterHub installer bundles a conda environment that includes SystemdSpawner to manage resource allocation, security, and process isolation for user notebooks by integrating with systemd and Linux cgroups. SystemdSpawner provides:
  • Memory and CPU limits per user
  • Fair scheduling independent of process count
  • Accurate resource accounting via cgroups
  • Path restrictions for user write access
  • Automatic log collection to journald with rotation
  • Process isolation through systemd units

Configuration file location

JupyterHub configuration is managed in:
/opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py

Basic resource configuration

Set default resource limits for all users:
c.JupyterHub.spawner_class = 'systemdspawner.SystemdSpawner'
c.SystemdSpawner.default_shell = '/bin/bash'
c.SystemdSpawner.mem_limit = '2G'
c.SystemdSpawner.cpu_limit = 1.0
c.SystemdSpawner.isolate_tmp = True
c.SystemdSpawner.isolate_devices = True
c.SystemdSpawner.disable_user_sudo = True
c.SystemdSpawner.unit_extra_properties = {'RuntimeDirectoryPreserve': 'no'}

Advanced resource configuration

Working directory and paths

As an admin, you can control how users access different parts of the workspace. For example, you might make shared data readonly while allowing notebook outputs to be writeable. To configure workspace locations:
c.SystemdSpawner.user_workingdir = '/shared/users/{USERNAME}'
c.SystemdSpawner.readonly_paths = ['/opt/shared-data']
c.SystemdSpawner.readwrite_paths = ['/tmp', '/shared/notebook-outputs']

Applying configuration changes

Before you restart the JupyterHub service, have all users save their work and log out. JupyterHub is configured through the jupyterhub_config.py file. Apply any configuration updates to that file, then restart the JupyterHub service:
# Validate configuration
sudo /opt/jupyterhub/bin/jupyterhub --config=/opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py --generate-config

# Restart JupyterHub
sudo systemctl restart jupyterhub

# Check status
sudo systemctl status jupyterhub

Security management

SSL/TLS certificate management

Renew self-signed certificates using the bundled DIY-SSL-CA script:
# Replace <HOSTNAME> with your JupyterHub server hostname
cd DIY-SSL-CA
bash create_noprompt.sh <HOSTNAME>
Once you have the new certificates, copy them to the /opt/jupyterhub/certs directory:
# Copy new certificates to /opt/jupyterhub/certs/
sudo cp your-cert.crt /opt/jupyterhub/certs/
sudo cp your-key.key /opt/jupyterhub/certs/

# Restart services
sudo systemctl restart nginx

Security hardening

Additional security configurations:
# Disable user sudo access in notebooks
c.SystemdSpawner.disable_user_sudo = True

# Isolate temporary directories
c.SystemdSpawner.isolate_tmp = True

# Isolate devices
c.SystemdSpawner.isolate_devices = True

# Set secure headers
c.JupyterHub.tornado_settings = {}
Refer to the official JupyterHub documentation for more information on using secure headers.

Monitoring & troubleshooting

Log management

To view JupyterHub service logs:
# View recent logs
sudo journalctl -u jupyterhub -f

# View logs for specific time period
sudo journalctl -u jupyterhub --since "2024-01-01" --until "2024-01-02"

# View logs with specific priority
sudo journalctl -u jupyterhub -p err

User Sessions Failing

Check user-specific logs:
sudo journalctl -u jupyter-username --no-pager

Need more help with JupyterHub?