Собрать и использовать кастомный Docker-образ для Jupyter Server

Требования к кастомному образу

Кастомный образ должен содержать:

1. Пользователя jovyan (uid 1000, gid 1000).

   Без него Distributed Train не сможет смонтировать NFS и запустить сервер.

2. Директории с владельцем jovyan:

   • /tmp/.jupyter_data

   • /tmp/.jupyter

   • /home/jovyan

   Необходимы для монтирования NFS и хранения данных.

3. Jupyter Server, установленный через pip install jupyter или из базового образа.

4. Точка входа через CMD со следующими флагами:

   • --ip=0.0.0.0

   • --no-browser

   • --allow-root

   • --port=8888

   • --NotebookApp.base_url=${NB_PREFIX}

   • --NotebookApp.allow_origin='https://*.ai.cloud.ru'

   Остальные аргументы, например --notebook-dir и дополнительные переменные окружения — на ваше усмотрение.

5. (Опционально) Системное расширение cloudru_extension.

   Обеспечивает интеграцию с Distributed Train и включает в себя мониторинг, защиту от OOM, проксирование и client_lib.

   Если вы решили не устанавливать расширение, удалите ссылку на cloudru_extension из jupyter_server_config.py. Иначе при запуске Jupyter Server возникнет ошибка kernel_manager_class could not be imported.

Пример создания кастомного образа из контейнеров NVIDIA

Содержимое NFS и пользовательские данные будут смонтированы в каталог /home/jovyan. Этот каталог будет установлен в качестве рабочего.

Модули, расположенные внутри каталога соответствующей переменной PYTHON_LIB_PATH, должны быть доступны для импорта интерпретатором Python. По умолчанию это каталог /home/user/conda/lib/python3.7. В него при запуске контейнера в регионе будет скопирована клиентская функция client_lib.

Создайте пользователя jovyan (uid 1000, gid 1000) и домашний каталог /home/jovyan. В этот каталог будет смонтировано хранилище пользователя. Все действия будут осуществляться из-под этого непривилегированного пользователя.

# [REQUIRED] Base image — any compatible environment with Python + CUDA
FROM nvcr.io/nvidia/pytorch:22.12-py3

# [OPTIONAL] Timezone — set as needed for your location
ENV TZ=Europe/Moscow
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

# Specifies that all subsequent commands must be executed as the root user
USER root

# [REQUIRED] Jovyan user (uid/gid 1000) — required for NFS mounting
RUN groupadd -g 1000 jovyan
RUN useradd -g jovyan -u 1000 -m jovyan

# [REQUIRED] Working directories owned by jovyan
RUN mkdir -p /tmp/.jupyter_data && chown -R jovyan /tmp/.jupyter_data && \
    mkdir -p /tmp/.jupyter && chown -R jovyan /tmp/.jupyter
RUN mkdir -p /home/jovyan && chown -R jovyan /home/jovyan

# [OPTIONAL] Copy your data — modify as needed
COPY InternImage /InternImage
RUN chown -R jovyan /InternImage

# [OPTIONAL] System build packages — install only what your project needs
RUN apt-get update --fix-missing && apt-get upgrade -y  &&\
    echo "8" apt-get install -y software-properties-common && apt-get update

# Install the necessary programs and libraries
RUN DEBIAN_FRONTEND=noninteractive apt-get install tzdata -qy &&\
    apt install -qy \
        python3-pip \
        build-essential \
        cmake \
        git \
        wget \
        zip \
        unzip \
        unrar \
        yasm \
        python3-dev \
        nano \
        vim \
        neovim \
        pkg-config \
        ffmpeg \
        libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libgstreamer-plugins-bad1.0-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-tools gstreamer1.0-x gstreamer1.0-alsa gstreamer1.0-gl gstreamer1.0-gtk3 gstreamer1.0-qt5 gstreamer1.0-pulseaudio &&\
    apt upgrade -qy &&\
    apt clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

# [OPTIONAL] Python environment variables — set as needed
ENV PYTHONUSERPATH="/home/user/.local"
ENV PATH=$PYTHONHOME/bin:$PATH

# [OPTIONAL] Python dependencies — list only the packages you need
RUN pip3 install -U --no-cache-dir torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
RUN pip3 install -U --no-cache-dir \
    openmim \
    opencv-python-headless \
    timm \
    mmdet \
    termcolor \
    yacs \
    pyyaml \
    scipy \
    pyyaml \
    transformers \
    huggingface_hub \
    safetensors \
    Pillow \
    psutil \
    PyYAML \
    requests \
    thop \
    tqdm \
    matplotlib

# [REQUIRED] Install Jupyter (if not present in the base image)
# RUN pip install jupyter

# [REQUIRED] cloudru_extension — platform integration (monitoring, OOM protection, proxying)
# If missing, Jupyter Server fails with "kernel_manager_class could not be imported"
# See Troubleshooting section for recovery steps
# RUN pip install cloudru_extension

# Change user to 'jovyan' again
USER jovyan

# [REQUIRED] Entry point — mandatory flags for Jupyter Server on the platform
CMD jupyter notebook \
              --notebook-dir=/home/jovyan \
              --ip=0.0.0.0 \
              --no-browser \
              --allow-root \
              --port=8888 \
              --NotebookApp.token='' \
              --NotebookApp.password='' \
              --NotebookApp.base_url=${NB_PREFIX} \
              --NotebookApp.allow_origin='https://*.ai.cloud.ru'

Фрагмент Docker-файла для добавления SSH

В этом разделе приведен порядок добавления кода в Docker-файл для SSH подключения к создаваемому Jupyter Server.

Порядок добавления SSH:

1. Создайте пользователя и группу:

   1. Создайте группу jovyan с GID 1000.

   2. Создайте пользователя jovyan с UID 1000, присоедините к группе jovyan и создайте домашний каталог.

2. Установите OpenSSH:

   1. Обновите пакеты в вашем контейнере.

   2. Установите openssh-server.

   3. Создайте необходимый каталог для sshd.

3. Настройте SSH:

   1. Измените конфигурацию SSH, чтобы отключить проверку ключей хоста (StrictHostKeyChecking no).

   2. Дайте права на чтение всем пользователям для всех файлов в /etc/ssh/.

   3. Отключите PAM в конфигурации SSH (UsePAM no).

   4. Установите PubkeyAcceptedAlgorithms для использования алгоритма ssh-rsa.

   5. Настройте авторизацию в параметрах конфигурации:

      AuthorizedKeysCommand /usr/bin/cat /etc/ssh/.ssh_aicloud/%u_keys
      AuthorizedKeysCommandUser %u
      
      

   6. Установите порт SSH на 2222.

4. Установите права доступа к файлам:

   1. Установите права доступа 600 для всех файлов в /etc/ssh/.

   2. Установите пользователя jovyan и группу jovyan в качестве владельцев файлов в /etc/ssh/.

5. Настройте запуск сервера SSH и Jupyter Notebook на необходимых портах с определенными конфигурационными параметрами (CMD).

6. Соберите образ из Docker-файла с помощью команды docker build, указав путь к вашему Docker-файлу.

   Пример: docker build -t my-image-name:path-to-your-dockerfile.

   Фрагмент Docker-файла для добавления SSH

   # Create group with ID 1000 called 'jovyan'
   RUN groupadd -g 1000 jovyan
   
   # Creates a user with ID 1000 belonging to the group 'jovyan' and creates a home directory
   RUN useradd -g jovyan -u 1000 -m jovyan
   
   # Updates the list of packages in the repositories Ubuntu
   RUN apt-get update
   
   # Installs OpenSSH Server to enable communication between containers via MPI (Message Passing Interface)
   RUN apt-get install -y --no-install-recommends openssh-server && \
       mkdir -p /var/run/sshd
   
   # Sets SSH setup to connect to containers without checking the host key
   RUN cat /etc/ssh/ssh_config | grep -v StrictHostKeyChecking > /etc/ssh/ssh_config.new && \
       echo "    StrictHostKeyChecking no" >> /etc/ssh/ssh_config.new && \
       mv /etc/ssh/ssh_config.new /etc/ssh/ssh_config
   
   # Grants read rights to SSH configuration files to all users
   RUN chmod -R o+r /etc/ssh/*
   
   # Disables use PAM (Pluggable Authentication Modules) in SSHD
   RUN cat /etc/ssh/sshd_config | grep -v UsePAM > /etc/ssh/sshd_config.new && \
       echo "UsePAM no" >> /etc/ssh/sshd_config.new && \
       mv /etc/ssh/sshd_config.new /etc/ssh/sshd_config
   
   # Sets key authentication algorithms, allowing ssh-rsa
   RUN cat /etc/ssh/sshd_config | grep -v "PubkeyAcceptedAlgorithms " > /etc/ssh/sshd_config.new && \
       echo "PubkeyAcceptedAlgorithms +ssh-rsa" >> /etc/ssh/sshd_config.new && \
       mv /etc/ssh/sshd_config.new /etc/ssh/sshd_config
   
   # Set up authorization
   RUN echo "AuthorizedKeysCommand /usr/bin/cat /etc/ssh/.ssh_aicloud/%u_keys" >> /etc/ssh/sshd_config
   RUN echo "AuthorizedKeysCommandUser %u" >> /etc/ssh/sshd_config
   
   # Sets port 2222 for SSH
   RUN cat /etc/ssh/sshd_config | grep -v "Port " > /etc/ssh/sshd_config.new && \
       echo "Port 2222" >> /etc/ssh/sshd_config.new && \
       mv /etc/ssh/sshd_config.new /etc/ssh/sshd_config
   
   # Sets SSH file permissions and changes owner to 'jovyan'
   RUN chmod 600 /etc/ssh/* && \
       chown jovyan:jovyan /etc/ssh/*
   
   # Starts the SSHD server and Jupyter Notebook with the specified parameters
   CMD /usr/sbin/sshd && jupyter notebook \
                       --notebook-dir=/home/jovyan \
                       --ip=0.0.0.0 \
                       --no-browser \
                       --allow-root \
                       --port=8888 \
                       --NotebookApp.token='' \
                       --NotebookApp.password='' \
                       --NotebookApp.base_url=${NB_PREFIX} \
                       --NotebookApp.allow_origin='https://*.ai.cloud.ru'
   
   

Создание и локальная проверка Docker-образа

Перед сборкой образа убедитесь в его работоспособности:

1. Проверьте, что образ наследуется от базового образа платформы, например, от образа cr.ai.cloud.ru/aicloud-jupyter/jupyter-server:0.0.100.

   Все кастомизации необходимо строить поверх базового образа. Это гарантирует совместимость с инфраструктурой платформы.

2. Проверьте ENTRYPOINT и CMD:

   • ENTRYPOINT не должен быть переопределен напрямую, так как это может нарушить внутренние скрипты инициализации платформы.

   • Если необходимо добавить действия перед запуском Jupyter Server, разместите их в файле /home/user/entrypoint.sh.

3. Проверьте настройки запуска Jupyter Server:

   • Порт — 8888.

   • Аргументы запуска не должны блокировать стандартные флаги: --ip=0.0.0.0, --no-browser, --allow-root, которые включены в базовый образ.

4. Создайте Docker-образ локально:

   1. Запустите создание образа:

      docker build --tag 'jupyter-custom-image' .
      
      

      Точка в конце команды означает, что в этом же каталоге должен находиться Docker-файл, созданный ранее. Docker-файл должен называться Dockerfile.

   2. Запустите проверку созданного образа:

      docker run -p 8888:8888 -e NB_PREFIX="/notebook/ai000001-00001/mynotebookname" -it jupyter-custom-image
      
      

   Проверьте, что Jupyter Server запускается на порту 8888 с нужным префиксом (переменная окружения http://localhost:8888/a100-mt/notebook/ai000001-00001/mynotebookname).