Deployment Overview of JupyterLab on Server¶

Prerequisites and Basic Requirements¶

The deployment of JupyterLab on the host server requires the following system prerequisites and configurations:

• Operating System: Ubuntu Linux.

• Privileges: Root (superuser) access is required for service management and configuration changes.

• Domain: The deployment is configured for the hostkey.in domain.

• Network Ports:

  • Port 443 (HTTPS) for external secure access via the reverse proxy.

  • Port 8888 (TCP) for the internal JupyterLab application service.

FQDN of the Final Panel¶

The final access point for the application is resolved via the Hostkey domain using the specific prefix and server identifier: labServer ID'.hostkey.in:443 (Note: Replace "Server ID" with the actual server identifier specific to your instance to form the complete FQDN, e.g., lab123.hostkey.in.)

File and Directory Structure¶

The application and its supporting services utilize the following directory structure on the host system:

• Data Directory: /opt/data serves as the primary storage location for JupyterLab notebooks and virtual environments.

  • Virtual Environment: /opt/data/jupyter

  • Jupyter Share Directory: /opt/data/jupyter/share/jupyter

• Nginx Configuration: /root/nginx contains the Docker Compose configuration for the reverse proxy.

• Systemd Service: /usr/lib/systemd/system/jupyterlab.service defines the service management unit.

• Certificates and Secrets: Nginx mounts certificates to /etc/letsencrypt (via Docker volume nginx_secrets) and user configurations to /etc/nginx/user_conf.d.

• System Home: The /home directory is mounted into the Nginx container.

Application Installation Process¶

The JupyterLab application is installed directly onto the Ubuntu host using package managers and a Python virtual environment:

1. System Packages: Core dependencies including python3, python3-pip, jupyter, and python3-virtualenv are installed via the apt package manager.

2. User Creation: A dedicated system user jupyter (UID 2841) and group jupyter (GID 2841) are created for execution context.

3. Virtual Environment: A Python virtual environment is initialized at /opt/data/jupyter.

4. Package Installation: The following Python packages are installed within the virtual environment:

   • jupyterlab

   • jupyter-core

   • voila

   • jupyter-server

5. Configuration Generation:

   • The Jupyter Lab configuration file is generated using the command /opt/data/jupyter/bin/jupyter lab --generate-config.

   • A password for access is generated using /opt/data/jupyter/bin/jupyter lab password.

6. Service Setup: A systemd service file is deployed to manage the application lifecycle.

Access Rights and Security¶

Security and access controls are implemented through the following mechanisms:

• Firewall: Access is restricted to port 443 (HTTPS) for external traffic. Internal traffic uses port 8888.

• User Context: The JupyterLab service runs as the root user and group, as defined in the jupyterlab.service unit file (User=root, Group=root).

• Network Isolation: The Nginx reverse proxy runs in host network mode (network_mode: host), directly accessing the host network stack.

• SSL/TLS: Secure connections are handled by the nginx-certbot container, which manages SSL certificates via Let's Encrypt.

Docker Containers and Their Deployment¶

A reverse proxy container is deployed using Docker Compose to handle SSL termination and traffic routing.

Deployment Location: /root/nginx Management Command:

docker compose up -d

Container Details:

• Image: jonasal/nginx-certbot:latest

• Restart Policy: unless-stopped

• Volumes:

  • nginx_secrets (external) mapped to /etc/letsencrypt.

  • Host path /data/nginx/user_conf.d mapped to /etc/nginx/user_conf.d.

  • Host path /home mapped to /home inside the container.

• Environment:

  • CERTBOT_EMAIL: Set to [email protected].

  • Configuration loaded from /data/nginx/nginx-certbot.env.

Proxy Servers¶

Traffic is routed through an Nginx reverse proxy container that provides SSL termination and custom domain support:

• Software: Nginx with Certbot integration.

• Image Source: jonasal/nginx-certbot.

• Configuration: The proxy configuration is generated and stored in /root/nginx/compose.yml.

• SSL Management: Automatic certificate generation and renewal are handled by the container's built-in Certbot functionality.

• Routing: The proxy forwards requests from port 443 to the internal JupyterLab service on port 8888.

Permission Settings¶

File and directory permissions are configured as follows:

• /opt/data: Owned by jupyter:jupyter with mode 0777 (read, write, execute for all).

• /opt/data/jupyter: Owned by jupyter:jupyter with mode 0755 (read, execute for others).

• /root/nginx: Owned by root:root with mode 0644.

• Configuration Files: The jupyterlab.service and compose.yml files are owned by root.

Location of Configuration Files and Data¶

• JupyterLab Config: /root/.jupyter/jupyter_lab_config.py and /root/.jupyter/jupyter_server_config.json.

• Nginx Docker Compose: /root/nginx/compose.yml.

• Nginx Environment: /data/nginx/nginx-certbot.env.

• Service Definition: /usr/lib/systemd/system/jupyterlab.service.

• Notebook Data: /opt/data/jupyter/share/jupyter.

Available Ports for Connection¶

The system exposes the following ports for network communication:

• Port 443: HTTPS (External access via Nginx proxy).

• Port 8888: TCP (Internal JupyterLab service, not directly exposed to the public internet).

Starting, Stopping, and Updating¶

The JupyterLab application is managed via the systemd service manager.

Start the Service:

systemctl start jupyterlab

Stop the Service:

systemctl stop jupyterlab

Restart the Service:

systemctl restart jupyterlab

Enable on Boot:

systemctl enable jupyterlab

Status Check:

systemctl status jupyterlab

Reload Daemon Configuration:

systemctl daemon-reload

To update the Nginx proxy configuration, modify the file at /root/nginx/compose.yml and run docker compose up -d within the /root/nginx directory.