Running Jupyter on a Server: A Step-by-Step Guide

Introduction

As the popularity of data science and machine learning continues to grow, running a Jupyter Notebook server becomes an essential skill for anyone working in these fields. In this article, we will walk through the process of setting up a Jupyter server on a remote server, covering both the basics and more advanced topics.

Prerequisites

Before we begin, make sure you have the following:

A remote server with Python installed (e.g., Ubuntu or CentOS)
Docker installed on your local machine
Basic knowledge of Linux commands and Docker configuration

Step 1: Setting up a Simple HTTP Server

To start with Jupyter, we need to set up a simple HTTP server. The easiest way to do this is using the built-in python3 -m http.server command. This will create a development server that listens on port 8000.

# Start the HTTP server
python3 -m http.server

Once the server is running, open your web browser and navigate to http://your-server-ip:8000. You should see a basic HTML page with links to various Python modules. Clicking on any of these links will start an interactive Python shell.

Step 2: Creating a Docker Image for Jupyter

To run Jupyter in a container, we need to create a Docker image that includes the necessary dependencies. We’ll use the official jupyter/scipy-notebook image as a starting point.

# Create a new directory for our project
mkdir jupyter-server

# Navigate into the project directory
cd jupyter-server

# Create a new file named `Dockerfile`

Create the Dockerfile with the following contents:

# Use an official Python image as a base
FROM python:3.9-slim

# Set the working directory to /app
WORKDIR /app

# Copy the requirements file
COPY requirements.txt .

# Install the dependencies
RUN pip3 install --no-cache-dir -r requirements.txt

# Copy the Jupyter configuration files
COPY jupyter.conf .

# Expose port 8888 for Jupyter
EXPOSE 8888

# Run the command to start Jupyter
CMD ["jupyter", "notebook", "--ip", "0.0.0.0", "--no-browser"]

This Dockerfile creates a new image based on the official Python 3.9 image, installs the necessary dependencies using pip, and copies the Jupyter configuration files.

# Create a file named requirements.txt

Create a new file named requirements.txt with the following contents:

jupyter-notebook=33add21fab64

This specifies that we need to pull the latest version of the jupyter/scipy-notebook image (33add21fab64).

# Build and run the Docker container
docker build -t jupyter-server .
docker run -p 8888:8888 --rm -it jupyter-server

Once the container is running, open your web browser and navigate to http://your-server-ip:8888. You should see the Jupyter interface.

Step 3: Installing JupyterHub

If you want to set up a single server with multiple user interfaces, you’ll need to use JupyterHub instead of Just Jupyter. JupyterHub is a more advanced deployment that provides additional features and configuration options.

# Install JupyterHub using pip
pip3 install jupyterhub

Create a new file named jupyterhub.py with the following contents:

from jupyterhub import Hub

hub = Hub()

@hub.login_callback
def callback(username, password):
    if username == "admin" and password == "password":
        return True
    else:
        return False

This sets up a basic login system using the jupyterhub module.

# Configure JupyterHub to use SSL termination
from jupyterhub.config import Config

config = Config()

config.serve_app = lambda handler, *args: handler(app)
config.jupyter_security = {
    "allow_sign_in": True,
    "auth_backend": {"class_name": "AuthBackend", "auth_backend_config": {}},
}

This configures JupyterHub to use SSL termination and allows users to sign in.

# Start the JupyterHub server
jupyterhub serve --port=8888

Once the JupyterHub server is running, you can access it using http://your-server-ip:8888.

Step 4: Using Nginx for SSL Termination

If you don’t want to use JupyterHub or prefer a more traditional deployment method, you can use Nginx as a reverse proxy to handle SSL termination.

# Install Nginx using pip
pip3 install nginx

Create a new file named nginx.conf with the following contents:

http {
    server {
        listen 443 ssl;
        ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
        ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;

        location / {
            proxy_pass http://localhost:8888;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

This sets up a basic Nginx configuration that listens on port 443 for HTTPS requests and proxies them to the Jupyter server running on http://localhost:8888.

# Create a symbolic link to the nginx.conf file
ln -s /etc/nginx/sites-available/nginx.conf /etc/nginx/conf.d/

Restart Nginx to apply the changes:

systemctl restart nginx

Once Nginx is running, you can access Jupyter using https://your-server-ip:443.

Conclusion

Running a Jupyter server on a remote server requires some additional configuration and setup, but it’s definitely possible. By following these steps, you should be able to get up and running with a Jupyter server that provides an interactive Python shell for users to access.

Remember to always keep your dependencies and software up-to-date to ensure the security and stability of your deployment.

Last modified on 2025-04-06