Saturn allows administrators to manage images for users. At the bottom of the admin page, you can add any docker image.

After doing so, the image is available in the Jupyter dashboard.

Users Images

Similarly, users can also upload images for themselves. These images are scoped such that they are not available by default for other users.

Building your own images

As long as Jupyter and the kernel you want are installed in the right place, any docker image you build should work with Saturn.  The easiest way to build images is to start with our base image and add to it.  Here are a few examples.  The only difference in both of these entries is a different base image.  The last few lines are cleanup lines, and they are not strictly necessary, but they definitely help reduce image sizes, which help your containers start faster.

Basic CPU image example

from saturncloud/saturnbase:2020.03.14.4

COPY environment.yml /tmp/environment.yml

USER ${NB_USER}
RUN ${CONDA_DIR}/bin/conda env update -n saturn --file /tmp/environment.yml && \
    ${CONDA_DIR}/envs/saturn/bin/python -m ipykernel install --name python3 --prefix=${CONDA_DIR} && \
    ${CONDA_DIR}/bin/conda clean -afy && \
    find ${CONDA_DIR} -type f,l -name '*.pyc' -delete && \
    find ${CONDA_DIR} -type f,l -name '*.a' -delete && \
    find ${CONDA_DIR} -type f,l -name '*.js.map' -delete

Basic GPU image example

from saturncloud/saturnbase-gpu:2020.03.14.4

COPY environment.yml /tmp/environment.yml

USER ${NB_USER}
RUN ${CONDA_DIR}/bin/conda env update -n saturn --file /tmp/environment.yml && \
    ${CONDA_DIR}/bin/conda env update -n base --file /tmp/jupyter.yml && \
    ${CONDA_DIR}/envs/saturn/bin/python -m ipykernel install --name python3 --prefix=${CONDA_DIR} && \
    ${CONDA_DIR}/bin/conda clean -afy && \
    find ${CONDA_DIR} -type f,l -name '*.pyc' -delete && \
    find ${CONDA_DIR} -type f,l -name '*.a' -delete && \
    find ${CONDA_DIR} -type f,l -name '*.js.map' -delete

Advanced Example


from saturncloud/saturnbase:2020.03.14.4

COPY jupyter.yml /tmp/jupyter.yml
COPY environment.yml /tmp/environment.yml

USER root
RUN apt-get -qq update && \
    apt-get -qq install --yes --no-install-recommends \
    build-essential \
     > /dev/null && \
    apt-get -qq purge && \
    apt-get -qq clean && \
    rm -rf /var/lib/apt/lists/*

USER ${NB_USER}
RUN ${CONDA_DIR}/bin/conda env update -n saturn --file /tmp/environment.yml && \
    ${CONDA_DIR}/bin/conda env update -n base --file /tmp/jupyter.yml && \
    ${CONDA_DIR}/envs/saturn/bin/python -m ipykernel install --name python3 --prefix=${CONDA_DIR} && \
    ${CONDA_DIR}/bin/jupyter nbextension enable --py --sys-prefix clustergrammer2 && \
    ${CONDA_DIR}/bin/jupyter labextension install @jupyter-widgets/jupyterlab-manager && \
    ${CONDA_DIR}/bin/conda clean -afy && \
    find ${CONDA_DIR} -type f,l -name '*.pyc' -delete && \
    find ${CONDA_DIR} -type f,l -name '*.a' -delete && \
    find ${CONDA_DIR} -type f,l -name '*.js.map' -delete

This is an example of the type of other customizations you can do.  

  • We're copying over, and applying jupyter.yml (a file that has any changes we want to make to the environment that runs jupyter)  we're also enabling a jupyter lab extension that was installed from jupyter.yml
  • We're installing build-essential  apt package.  Note that we switch to the root  user before doing so, and back to the ${NB_USER}  after.

Example with PIP

This example installs python 3.7.5 and pip into the saturn  conda environment, and then calls pip install -r  on the requirements.txt file.  We also execute our standard conda cleanup commands, which may not be necessary, but help keep image sizes smaller.

from saturncloud/saturnbase:2020.03.14.4

COPY requirements.txt /tmp/requirements.txt

USER ${NB_USER}
RUN ${CONDA_DIR}/bin/conda install -n saturn python=3.7.5 pip && \
    ${CONDA_DIR}/envs/saturn/bin/pip install -r /tmp/requirements.txt && \
    ${CONDA_DIR}/envs/saturn/bin/pip install ipykernel && \
    ${CONDA_DIR}/bin/conda clean -afy && \
    find ${CONDA_DIR} -type f,l -name '*.pyc' -delete && \
    find ${CONDA_DIR} -type f,l -name '*.a' -delete && \
    find ${CONDA_DIR} -type f,l -name '*.js.map' -delete

RUN ${CONDA_DIR}/envs/saturn/bin/python -m ipykernel install --name python3 --prefix=/srv/conda

Docker Registries

By default, Saturn authenticates with the Elastic Container Registry (ECR) for the AWS account that it's deployed into.  If you build and push image there, you can easily add it to Saturn.

Authenticating with ECR

aws ecr get-login --no-include-email | bash

Pushing to ECR

docker build -t ${registry}/${image_and_tag} .
docker push ${registry}/${image_and_tag}

Your ECR registry looks something like 123456789.dkr.ecr.us-east-1.amazonaws.com  .  You'll need to replace us-east-1  with your region, and 123456789  with your aws account ID

Did this answer your question?