Deployment Overview of Jupyter Notebook on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux-based server environment with the following specifications:

Operating System: Ubuntu (compatible with apt package manager).
Privileges: Root access or sudo privileges are required for installation and service management.
Domain: The server must be associated with the hostkey.in zone.
Ports:
Internal application port: 8888
External HTTPS port: 443

The application is accessible via the following Fully Qualified Domain Name (FQDN) format:

The application utilizes the following directory structure for configuration, data, and execution:

/opt/data: Root directory for Jupyter data and virtual environment.
/opt/data/jupyter: Location of the Python virtual environment.
/root/.jupyter: Location of the Jupyter configuration files.
/root/nginx: Directory containing the Docker Compose configuration for the proxy.
/usr/lib/systemd/system/jupyter-notebook.service: Systemd service unit file.
/home: Mounted volume for user home directories within the proxy container.

The Jupyter Notebook application is installed using the following steps:

A dedicated system user and group named jupyter (UID/GID: 2841) are created.
Required system packages are installed via apt:
python3
python3-pip
jupyter
python3-virtualenv
A Python virtual environment is created at /opt/data/jupyter.
The following Python packages are installed within the virtual environment:
notebook
voila
virtualenv
jupyter-server
The Jupyter configuration is generated and modified to allow cross-origin requests (c.ServerApp.allow_origin = '*').
A password is generated for the Jupyter Notebook interface.
The application is registered as a systemd service named jupyter-notebook.

A reverse proxy and SSL termination layer is deployed using Docker Compose. The deployment includes:

Image: jonasal/nginx-certbot:latest
Restart Policy: unless-stopped
Network Mode: host
Volumes:
nginx_secrets: External volume mapped to /etc/letsencrypt for SSL certificates.
/data/nginx/user_conf.d: Mapped to /etc/nginx/user_conf.d for custom Nginx configurations.
/home: Mapped to /home inside the container.
Environment:
CERTBOT_EMAIL: Set to [email protected].
Configuration File: The Docker Compose file is located at /root/nginx/compose.yml.

The application is fronted by an Nginx container running Certbot for SSL management:

Service Name: nginx
Function: Handles HTTPS traffic on port 443 and forwards requests to the internal Jupyter instance.
SSL: Managed automatically via Certbot.
Custom Domains: Configured to serve the hostkey.in zone with the specific prefix.

File and directory permissions are configured as follows:

/opt/data: Owned by jupyter:jupyter with mode 0777.
/opt/data/jupyter: Owned by jupyter:jupyter with mode 0755.
/root/nginx: Owned by root:root with mode 0644.
/root/nginx/compose.yml: Owned by root:root with mode 0644.
The Jupyter service runs as the root user and group within the systemd service definition.

Key configuration and data files are located at:

Jupyter Config: /root/.jupyter/jupyter_server_config.json and /root/.jupyter/jupyter_notebook_config.py.
Docker Compose: /root/nginx/compose.yml.
Nginx Environment: /data/nginx/nginx-certbot.env.
Data Directory: /opt/data/jupyter/share/jupyter (Notebook working directory).
PID File: /run/jupyterlab.pid.

The following ports are utilized for the application:

The Jupyter Notebook service is managed via systemd. Use the following commands to control the service:

To manage the Docker proxy container, navigate to the configuration directory and use Docker Compose commands:

cd /root/nginx
docker compose up -d