Deployment Overview of JupyterLab on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux-based operating system, specifically Ubuntu, with root privileges to execute installation scripts and manage system services. The following components and settings are required:

Operating System: Ubuntu
Privileges: Root access is mandatory for user creation, service management, and Docker operations.
Domain: hostkey.in
Ports:
Internal application port: 8888
External HTTPS port: 443

FQDN of the Final Panel¶

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

lab<Server ID>.hostkey.in:443

Replace <Server ID> with the specific identifier assigned to the server instance.

File and Directory Structure¶

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

/opt/data: Root directory for Jupyter data and virtual environments.
/opt/data/jupyter: Location of the Python virtual environment.
/root/.jupyter: Directory containing JupyterLab configuration files.
/root/nginx: Directory containing Docker Compose files for the proxy server.
/data/nginx: Directory for Nginx user configurations and environment files.
/etc/letsencrypt: Mount point for SSL certificates managed by Certbot.
/home: User home directories mounted for the Nginx container.

Application Installation Process¶

JupyterLab is installed using a Python virtual environment and managed as a systemd service. The installation process includes:

Creating a system group and user named jupyter with UID and GID 2841.
Installing system packages: python3, python3-pip, jupyter, and python3-virtualenv.
Creating a virtual environment at /opt/data/jupyter.
Installing the following Python packages within the virtual environment:
jupyterlab
jupyter-core
voila
jupyter-server
Generating the JupyterLab configuration file.
Setting the allow_origin parameter to * in the configuration.
Generating a password for authentication.
Installing the systemd service file at /usr/lib/systemd/system/jupyterlab.service.

Docker Containers and Their Deployment¶

The deployment includes a Docker container for the Nginx proxy and SSL management. The container is deployed using Docker Compose with the following specifications:

Image: jonasal/nginx-certbot:latest
Restart Policy: unless-stopped
Network Mode: host
Environment Variables:
CERTBOT_EMAIL: [email protected]
Volumes:
nginx_secrets mapped to /etc/letsencrypt
/data/nginx/user_conf.d mapped to /etc/nginx/user_conf.d
/home mapped to /home
Compose File Location: /root/nginx/compose.yml

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 and handles SSL termination using Certbot.

Proxy Image: jonasal/nginx-certbot:latest
SSL Management: Automated via Certbot with the email [email protected].
Configuration: Custom Nginx configurations are stored in /data/nginx/user_conf.d.
External Port: 443 (HTTPS)
Internal Path: Empty string ("")
External Path: /

Permission Settings¶

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.
System user jupyter is created with a home directory.

Location of Configuration Files and Data¶

Key configuration and data files are located at:

JupyterLab Config: /root/.jupyter/jupyter_lab_config.py and /root/.jupyter/jupyter_server_config.json.
Systemd Service: /usr/lib/systemd/system/jupyterlab.service.
Docker Compose: /root/nginx/compose.yml.
Nginx Environment: /data/nginx/nginx-certbot.env.
Notebook Data: /opt/data/jupyter/share/jupyter.

Available Ports for Connection¶

The following ports are configured for the application:

Internal Port: 8888 (Used by the JupyterLab service internally).
External Port: 443 (HTTPS traffic routed through the Nginx proxy).

Starting, Stopping, and Updating¶

The JupyterLab service is managed using systemctl. The following commands are used to control the service:

Start the service:
```
systemctl start jupyterlab
```
Stop the service:
```
systemctl stop jupyterlab
```
Enable the service on boot:
```
systemctl enable jupyterlab
```

Reload systemd daemon and restart:

systemctl daemon-reload
systemctl restart jupyterlab

Check service status:
```
systemctl status jupyterlab
```

For the Nginx proxy container, use the following commands from the /root/nginx directory:

Start/Restart container:
```
docker compose up -d
```
Stop container:
```
docker compose down
```