JupyterHub — это мощное средство, которое позволяет создавать персонализированные рабочие пространства для групп пользователей, обеспечивая доступ к ноутбукам Jupyter через веб-интерфейс.

Cуществуют «три» варианта установки JupyterHub в зависимости от Ваших потребностей:

1. Локальная установка Jupyter Notebook: работа с Jupyter Notebook непосредственно на локальном компьютере.
2. Littlest JupyterHub (также известный как TLJH): установка минимальной версии JupyterHub для обеспечения базовых функциональных возможностей, является легким методом установки JupyterHub на одну виртуальную машину.
3. JupyterHub с использованием Docker: развёртывание JupyterHub в контейнеризованной среде при помощи Docker.
4. Zero to JupyterHub для Kubernetes: установка JupyterHub с использованием Kubernetes для масштабируемости и управления контейнерами.

В данной статье вы найдете подробное пошаговое руководство для трех первых вариантов установки JupyterHub. 

Последний вариант будет рассмотрен в отдельной публикации.

Вариант №1: Jupyter Notebook на локальный компьютер

Для установки и запуска Jupyter Notebook на вашем локальном компьютере выполните следующие шаги в командной строке:

pip install notebook

jupyter notebook

Вариант №2: Littlest JupyterHub на виртуальную машину

Шаг 1. Аренда облачного сервера

Первым шагом в развертывании JupyterHub является получение облачного сервера. Облачные провайдеры, такие как, Yandex Cloud , VK Cloud, Selectel или Timeweb Cloud, предоставляют возможность арендовать виртуальные серверы в облаке. 

Выберите облачного провайдера, который наиболее соответствует вашим требованиям, и следуйте их инструкциям для создания и настройки виртуального сервера. Обычно вам будет предложено выбрать операционную систему и фигурацию сервера в соответствии с вашими потребностями, такими как количество ядер процессора, объем оперативной памяти и размер хранилища.

После создания сервера в облаке, получите доступ к нему посредством SSH или других предоставленных средств удаленного доступа.

Я собираюсь установить JupyterHub на сервере, предоставляемом провайдером Selectel, учитывая разнообразие серверов, которые они предлагают. Выбор данного провайдера обусловлен возможностью подбора серверов, оптимизированных для разработки, анализа данных и обучения моделей машинного обучения. Это позволит мне создать небольшую платформу для обработки данных, учитывая бюджетные ограничения. 

Далее подключаемся к серверу через командную строку для удобства дальнейшей работы. На macOS это выглядит следующим образом: заходим в терминал и прописываем учетные данные для доступа к серверу.

zurab@MacBook-Air ~ % ssh root@80.76.60.75
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
root@80.76.60.75's password: 
# далее вводим пароль

Шаг 2. Установка Littlest JupyterHub

Для начала требуется установить следующие пакеты: python3, python3-dev, curl и git.

sudo apt install python3 python3-dev git curl

Выполните следующую команду в терминале, чтобы установить JupyterHub. Не забудьте заменить <admin-user-name> на имя (он же и логин для входа) первого пользователя-администратора:

curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin <admin-user-name>

Это займет 5-10 минут, и будет сообщено Done!, когда процесс установки будет завершен. Скопируйте общедоступный IP вашего сервера и попробуйте получить доступ http://<public-ip> из вашего браузера. Если все прошло хорошо, вам откроется страница входа в JupyterHub.

Теперь вы можете войти в систему, используя имя пользователя администратора, которое вы указали на предыдущем этапе. Выберите любой надежный пароль для этой учетной записи и обязательно его сохраните, так как это будет пароль для вашей административной учетной записи.

Поздравляю, у вас есть работающий JupyterHub!

Шаг 3. Установка пакетов conda / pip для всех пользователей

Войдите в систему как администратор и откройте терминал, и поочередно выполните нижеприведенные команды :

sudo -E conda install -c conda-forge gdal
sudo -E pip install there

Шаг 4. Настройка HTTPS

Теперь настал момент установки SSL-сертификата, однако для этого необходимо иметь свой домен. Если у вас его нет, вам нужно его приобрести. Приобрести себе домен вы можете: тут и тут. 

Для установки соединения между вашим сервером и доменом или поддоменом, выполните привязку A-записи к IP-адресу вашего сервера. 

Чтобы включить HTTPS через letsencrypt:

sudo tljh-config set https.enabled true

где you@example.com — ваш адрес электронной почты и jupyter.example.com — домен, на котором будет запущен ваш хаб.

sudo tljh-config set https.letsencrypt.email you@example.com
sudo tljh-config set https.letsencrypt.domains jupyter.example.com

После выполнения вышеприведенных команд, ваша конфигурация должна быть обновлена следующим образом:

sudo tljh-config show

users:
  admin:
  - Zurab
https:
  enabled: true
  letsencrypt:
    email: info@shakhbanov.org
    domains: jupyter.shakhbanov.org

Теперь требуется перезапустить прокси-сервер для применения новой конфигурации. Выполните следующую команду:

sudo tljh-config reload proxy

Вариант №3: JupyterHub на Docker-е

Инструкции по установке Docker на сервер легко доступны в интернете. Если вам не хочется заниматься установкой Docker, вы можете воспользоваться услугами хостинга на Timeweb Cloud, где Docker уже установлен заранее. Также учитывайте, что на момент написания статьи Timeweb Cloud не предоставляет серверы с графическими процессорами (GPU)

Шаг 1. Образ JupyterHub

Чтобы получить последний образ JupyterHub и запустить контейнер jupyterhub, выполните эту команду в своем терминале.

docker run -d -p 8000:8000 --name jupyterhub jupyterhub/jupyterhub jupyterhub

После запуска контейнера с JupyterHub, вы сможете получить доступ к нему через порт 8000 (http://your_ip:8000). Однако вы не сможете войти, поскольку не создана учетная запись системного пользователя, то есть администратора.

Шаг 2. Создание учетной записи

Для создания системного пользователя выполните следующие команды:

docker exec -it jupyterhub bash

adduser <admin_name>

После создания учетной записи администратора, возможно, вы столкнетесь со следующей ошибкой при попытке входа в JupyterHub

Для устранения данной ошибки необходимо установить Jupyter Notebook:

pip install notebook

И наверняка вас попросят обновить пакет pip в Python 3:

python3 -m pip install --upgrade pip

Поздравляю, теперь вы можете без проблем войти в JupyterHub под своей учетной записью. Но прежде чем начать работу, выполните установку пакетов conda для всех пользователей.

Шаг 3. Установка NGINX и создание конфигурационного файла для веб-приложения

Для установки соединения между вашим сервером и доменом или поддоменом, выполните привязку A-записи к IP-адресу вашего сервера.

Если NGINX еще не установлен на вашем сервере, выполните следующие команды:

sudo apt update
sudo apt install nginx

Далее мы создаем конфигурационный файл NGINX для веб-приложения. Обычно файлы конфигурации хранятся в /etc/nginx/sites-available/. Создайте новый файл, например, jupyterhub, с помощью текстового редактора:

sudo nano /etc/nginx/sites-available/jupyterhub

Пример базовой конфигурации:

server {
    listen 80;
    server_name jupyterhub.your-domain.com www.jupyterhub.your-domain.com;

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

Шаг 4. Создание символической ссылки и проверка конфигурации и перезапуск NGINX

Создайте символическую ссылку на ваш конфигурационный файл в папке sites-enabled, чтобы активировать его:

sudo ln -s /etc/nginx/sites-available/jupyterhub /etc/nginx/sites-enabled/

Проверьте конфигурацию на наличие ошибок:

sudo nginx -t

Если конфигурация корректна, перезапустите NGINX:

sudo systemctl restart nginx

Шаг 5. Установка SSL-сертификата

Для установки SSL-сертификата вы можете воспользоваться Let’s Encrypt. Установите Certbot:

sudo apt install certbot python3-certbot-nginx

Затем выпустите SSL-сертификат для вашего домена (замените domain.com):

sudo certbot --nginx -d jupyterhub.your-domain.com -d www.jupyterhub.your-domain.com

Следуйте инструкциям Certbot для завершения установки. Certbot автоматически обновит конфигурацию NGINX, добавив SSL-сертификаты. После завершения, ваши запросы будут обслуживаться через HTTPS.

Перезапустите NGINX, чтобы применить изменения в конфигурации:

sudo systemctl restart nginx

Теперь веб-приложение JupyterHub будет доступно через HTTPS с помощью NGINX, который также выполняет проксирование запросов к вашему приложению.

После успешной установки SSL-сертификата рекомендуется улучшить читаемость конфигурационного файла NGINX, приведя его к более классическому и структурированному виду, и включить явный редирект на HTTPS.

Снова переходим к конфигурационному файлу

sudo nano /etc/nginx/sites-available/jupyterhub

и меняем содержимое на 

server {
    listen 80;
    server_name jupyterhub.your-domain.com www.jupyterhub.your-domain.com;
    
    # Redirecting to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name jupyterhub.your-domain.com www.jupyterhub.your-domain.com;

    ssl_certificate /etc/letsencrypt/live/jupyterhub.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/jupyterhub.your-domain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

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

После сохранения проверяем конфигурацию на наличие ошибок:

sudo nginx -t

Если конфигурация корректна, перезапустите NGINX:

sudo systemctl restart nginx

Шаг 6. Автообновление SSL-сертификата с помощью Certbot.

Для автоматического обновления SSL-сертификатов с помощью Certbot, необходимо настроить задачу cron (планировщик задач) для периодической проверки и обновления сертификатов. Сделать это можно следующим образом:

Откройте файл cron для редактирования:

sudo crontab -e

Добавьте строку, которая будет запускать Certbot для автоматической проверки и обновления сертификатов. Например, для обновления сертификатов каждый день в 2 часа ночи, вы можете добавить следующую строку:

0 2 * * * certbot renew

Сохраните файл и закройте редактор.

Эта строка задачи cron вызывает команду certbot renew, которая автоматически проверяет все установленные SSL-сертификаты и обновляет их, если это необходимо. Certbot умеет проверять срок действия сертификатов и обновлять их, если они скоро истекут.

Чтобы убедиться, что задача cron настроена правильно, вы можете выполнить следующую команду:

sudo certbot renew --dry-run

Эта команда выполняет проверку обновления сертификатов в режиме «сухого запуска», не внося никаких фактических изменений. Если команда завершится успешно, то задача cron должна быть правильно настроена.

После настройки задачи cron, Certbot будет автоматически проверять и обновлять SSL-сертификаты по расписанию. Вы можете следить за процессом обновления, проверяя логи Certbot:

sudo tail -f /var/log/letsencrypt/letsencrypt.log

Это позволит вам видеть, когда сертификаты успешно обновлены или если возникнут какие-либо проблемы.

Теперь у вас настроено автоматическое обновление SSL-сертификатов с помощью Certbot через задачу cron, что обеспечит надежную защиту вашего веб-приложения.

Post Scriptum

Помните, что процесс установки и настройки может различаться в зависимости от конкретных требований и конфигурации вашей среды. Всегда обращайтесь к официальной документации JupyterHub, Docker и к вашему провайдеру для получения наиболее актуальных инструкций.

Post Scriptum 2.0

Если, так же как и я, вы предпочитаете использовать не JupyterLab, а Jupyter Notebook.