How to Set Up a JupyterHub Server for Team Collaboration

How to Set Up a JupyterHub Server for Team Collaboration

JupyterHub is a multi-user server that allows entire teams to work in Jupyter notebooks simultaneously, each in their own isolated environment. Running JupyterHub on your Breeze gives your data science team a centralized, collaborative workspace without relying on third-party hosted solutions.

Prerequisites

• A Breeze instance with at least 4 GB of RAM and 2 vCPUs
• Ubuntu 22.04 or later installed
• Root or sudo access
• A domain name pointed to your Breeze (optional but recommended for HTTPS)

Installing Python and JupyterHub

Start by updating your system and installing the required dependencies:

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-pip python3-venv nodejs npm
sudo npm install -g configurable-http-proxy

Create a virtual environment and install JupyterHub along with the notebook package:

sudo python3 -m venv /opt/jupyterhub
sudo /opt/jupyterhub/bin/pip install jupyterhub notebook jupyterlab

Configuring JupyterHub

Generate a default configuration file:

sudo mkdir -p /etc/jupyterhub
cd /etc/jupyterhub
sudo /opt/jupyterhub/bin/jupyterhub --generate-config

Edit /etc/jupyterhub/jupyterhub_config.py and set the following options:

c.JupyterHub.bind_url = 'http://0.0.0.0:8000'
c.Spawner.default_url = '/lab'
c.JupyterHub.admin_access = True
c.Authenticator.admin_users = {'your_admin_user'}
c.LocalAuthenticator.create_system_users = True

Adding System Users for Team Members

Each team member needs a system account on your Breeze. Create users with:

sudo adduser teammate1
sudo adduser teammate2

These users will authenticate against the system PAM module and receive their own isolated Jupyter workspace.

Running as a Systemd Service

Create a systemd unit file at /etc/systemd/system/jupyterhub.service:

[Unit]
Description=JupyterHub
After=network.target

[Service]
ExecStart=/opt/jupyterhub/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py
WorkingDirectory=/etc/jupyterhub
Restart=always
User=root

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable jupyterhub
sudo systemctl start jupyterhub

Enabling HTTPS with Nginx

For production use, place Nginx in front of JupyterHub and terminate SSL with Let’s Encrypt:

sudo apt install -y nginx certbot python3-certbot-nginx
sudo certbot --nginx -d jupyter.yourdomain.com

Configure the Nginx site to proxy to http://127.0.0.1:8000 with WebSocket support enabled for interactive kernel communication.

Installing Shared Kernels and Extensions

Install data science packages system-wide so all users benefit:

sudo /opt/jupyterhub/bin/pip install numpy pandas matplotlib scikit-learn seaborn

You can also install R or Julia kernels to support polyglot data teams working in a single JupyterHub environment on your Breeze.