Deployment Overview of JupyterLab on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux server running Ubuntu. The following system-level prerequisites must be met before installation: - Operating System: Ubuntu - Privileges: Root access or sudo privileges are required for system configuration and service management. - Ports: The application listens on port 8888 by default, though the specific port is managed via the systemd service configuration. - Domain: A valid domain name is required for the Nginx reverse proxy and SSL certificate generation via Certbot.

File and Directory Structure¶

The application and its supporting components utilize the following directory structure: - /opt/data: The primary data directory for JupyterLab, owned by the jupyter user and group. - /opt/data/jupyter: The Python virtual environment directory containing the JupyterLab installation. - /root/.jupyter: The location of the JupyterLab configuration files, specifically jupyter_lab_config.py and jupyter_server_config.json. - /root/nginx: The directory containing the Docker Compose configuration for the Nginx proxy. - /data/nginx/user_conf.d: The directory mounted for custom Nginx user configurations. - /data/nginx/nginx-certbot.env: The environment file containing Nginx and Certbot settings. - /etc/letsencrypt: The directory for SSL certificates managed by the nginx_secrets volume.

Application Installation Process¶

The JupyterLab application is installed using a Python virtual environment on the host system. The installation process involves the following steps: 1. System Packages: Install python3, python3-pip, jupyter, and python3-virtualenv using the apt package manager. 2. User and Group Creation: Create a system group named jupyter (GID 2841) and a system user named jupyter (UID 2841) assigned to this group. 3. Virtual Environment Setup: - Create the directory /opt/data/jupyter. - Initialize a Python 3 virtual environment in /opt/data/jupyter using the virtualenv command. 4. Package Installation: Install the following Python packages into the virtual environment: - jupyterlab - jupyter-core - voila - jupyter-server 5. Configuration Generation: Generate the default JupyterLab configuration file using the command jupyter lab --generate-config. 6. Password Setup: Generate a secure password for the JupyterLab server using the jupyter lab password command.

Access Rights and Security¶

Security and access control are implemented through user isolation and firewall configurations managed by the reverse proxy: - User Isolation: The JupyterLab application runs under the jupyter user context for file operations, while the systemd service is configured to run as root to bind to network interfaces. - CORS Configuration: The jupyter_lab_config.py file is modified to allow cross-origin requests by setting c.ServerApp.allow_origin = '*'. - Network Binding: The application is configured to listen on 0.0.0.0, allowing connections from any network interface. - Reverse Proxy: Access to the application is routed through an Nginx container, which handles SSL termination and domain routing.

Docker Containers and Their Deployment¶

A Docker container is deployed to manage the Nginx reverse proxy and SSL certificates. The deployment utilizes Docker Compose with the following specifications: - Image: jonasal/nginx-certbot:latest - Restart Policy: unless-stopped - Network Mode: host - Environment Variables: - CERTBOT_EMAIL: Set to [email protected] - Additional environment variables are loaded from /data/nginx/nginx-certbot.env. - Volumes: - nginx_secrets: An external volume mounted to /etc/letsencrypt for SSL certificate storage. - /data/nginx/user_conf.d: Mounted to /etc/nginx/user_conf.d for custom Nginx configurations. - /home: Mounted to /home to provide access to home directories.

The container is started using the command docker compose up -d executed from the /root/nginx directory.

Proxy Servers¶

The Nginx container acts as a reverse proxy for the JupyterLab application, providing SSL encryption and domain-based routing. - SSL Management: Certbot is integrated within the Nginx container to automatically generate and renew SSL certificates. - Configuration: Custom Nginx configurations are placed in the /data/nginx/user_conf.d directory on the host, which is mounted into the container. - Email Notification: Certificate renewal notifications are sent to [email protected].

Permission Settings¶

File and directory permissions are configured to ensure proper access for the application and the system user: - /opt/data: Set to mode 0777 with ownership jupyter:jupyter. - /opt/data/jupyter: Set to mode 0755 with ownership jupyter:jupyter. - /root/nginx: Set to mode 0644 with ownership root:root. - /root/nginx/compose.yml: Set to mode 0644 with ownership root:root.

Starting, Stopping, and Updating¶

The JupyterLab application is managed as a systemd service named jupyterlab. The service file is located at /usr/lib/systemd/system/jupyterlab.service.

Service Configuration Details: - Type: Simple - Working Directory: /opt/data - ExecStart Command:

/opt/data/jupyter/bin/jupyter-lab --config=/root/.jupyter/jupyter_server_config.json --allow-root --ip=0.0.0.0 --no-browser --notebook-dir=/opt/data/jupyter/share/jupyter

Management Commands: - Start the service:

systemctl start jupyterlab

systemctl stop jupyterlab

systemctl enable jupyterlab

systemctl daemon-reload

systemctl status jupyterlab