Deployment Overview of JupyterLab on Server¶
Prerequisites and Basic Requirements¶
To ensure a successful deployment, the following requirements must be met:
-
Operating System: Ubuntu (recommended).
-
Privileges: Root or sudo access is required for package installation and service configuration.
-
Python Environment: Python 3 and
pipmust be available in the system repositories. -
Ports:
-
Port
443: External HTTPS access via Nginx. -
Port
8888: Internal application port.
FQDN of the final panel on the hostkey.in domain¶
The application is accessible through a specific subdomain template based on your server ID.
| Parameter | Value |
|---|---|
| Prefix | lab |
| Domain | hostkey.in |
| Full template | lab{Server_ID_from_Invapi}.hostkey.in |
File and Directory Structure¶
The following directories are used for application data, configurations, and proxy settings:
-
/opt/data: Main data directory owned by thejupyteruser. -
/opt/data/jupyter: Virtual environment and Jupyter installation files. -
/root/.jupyter/: Configuration files for the Jupyter server. -
/root/nginx/: Nginx configuration and Docker Compose files. -
/data/nginx/user_conf.d/: Custom Nginx virtual host configurations. -
/data/nginx/nginx-certbot.env: Environment variables for the Nginx container.
Application installation process¶
The installation follows a multi-step process involving system package management and Python environment setup:
-
System Package Installation: The system installs
python3,python3-pip,jupyter, andpython3-virtualenvvia theaptpackage manager. -
User and Group Setup: A dedicated system user named
jupyter(UID2841) and groupjupyter(GID2841) are created to manage application processes. -
Environment Isolation: A Python virtual environment is created at
/opt/data/jupyter. -
Application Installation: The following packages are installed within the virtual environment:
-
jupyterlab -
jupyter-core -
voila -
jupyter-server -
Configuration Generation:
-
A Jupyter Lab configuration file is generated at
/root/.jupyter/jupyter_lab_config.py. -
The
c.ServerApp.allow_originsetting is updated to'*'to allow cross-origin requests. -
A login password is automatically generated and configured for the server.
-
Service Integration: A systemd service named
jupyterlabis created and enabled to ensure the application starts on boot.
Access Rights and Security¶
-
User Isolation: The application runs under a dedicated
jupyteruser for data management, while the systemd service manages the process execution. -
Firewall: Only necessary ports (primarily 443) should be exposed to the public internet.
-
SSL/TLS: SSL certificates are managed via Certbot and served through an Nginx proxy container.
Databases¶
No external database management system is required for this deployment, as JupyterLab operates using local file storage within /opt/data.
Docker Containers and Their Deployment¶
The deployment utilizes a Docker container to handle reverse proxying and SSL certificate management:
| Container Name | Image | Ports | Volumes | Environment Variables | Restart Policy |
|---|---|---|---|---|---|
nginx | jonasal/nginx-certbot:latest | Host Network | - nginx_secrets:/etc/letsencrypt- /data/nginx/user_conf.d:/etc/nginx/user_conf.d- /home:/home | [email protected] (plus variables from /data/nginx/nginx-certbot.env) | unless-stopped |
Custom Scripts and Additional Setup¶
The installation performs several automated setup actions:
-
Virtual Environment Initialization: A shell command is used to initialize the Python virtual environment at
/opt/data/jupyter. -
Configuration Modification: The installer modifies the Jupyter configuration file directly to permit specific origin requests.
-
Password Generation: An automated process generates a secure password for the Jupyter interface during setup.
Application Update Instructions¶
To update the main application, perform the following steps:
-
Update Python Packages: Activate the virtual environment and upgrade the installed packages:
-
Restart Service: Apply changes by restarting the systemd service:
Location of configuration files and data¶
-
Jupyter Configuration:
/root/.jupyter/jupyter_lab_config.py -
Jupyter Server Config:
/root/.jupyter/jupyter_server_config.json -
Application Data:
/opt/data/jupyter/share/jupyter -
Nginx User Configs:
/data/nginx/user_conf.d/
Available ports for connection¶
- HTTPS (Web Interface):
443
Starting and Stopping the application¶
The application is managed via systemd. Use the following commands:
-
Start JupyterLab:
-
Stop JupyterLab:
-
Check Status:
Proxy Servers (Nginx, Traefik, SSL, custom domains)¶
The application is served through an Nginx container (jonasal/nginx-certbot) running in host network mode. This container handles:
-
SSL Termination: Uses Certbot to manage certificates stored in the
nginx_secretsvolume. -
Reverse Proxying: Forwards traffic from the external domain (e.g.,
lab{Server_ID_from_Invapi}.hostkey.in) to the internal JupyterLab service running on port8888.