Provide users with access to custom images

This documentation provides step-by-step instructions to provide your users with access to custom images within their JupyterLab environments. You can use the information on this page to create custom environments for your user’s workflows. The process involves utilizing:

• Docker

• AWS Command Line Interface

• Amazon Elastic Container Registry

• Amazon SageMaker AWS Management Console

After following the guidance on this page, JupyterLab users on the Amazon SageMaker domain will have access to the custom image and environment from their Jupyter spaces to empower their machine learning workflows.

Important

This page assumes that you have the AWS Command Line Interface and Docker installed on your local machine.

To have your users successfully run their image within JupyterLab, you must do the following:

To have your users successfully run the image

1. Create the Dockerfile

2. Build the image from the Dockerfile

3. Upload the image to Amazon Elastic Container Registry

4. Attach the image to you Amazon SageMaker domain

5. Have your users access the image from your JupyterLab space

Step 1: Create the Dockerfile

Create a Dockerfile to define the steps needed to create the environment needed to run the application in your users' containers.

Important

Your Dockerfile must meet the specifications provided in Dockerfile specifications.

Use the following Dockerfile template to create an Amazon Linux 2 image:

FROM public.ecr.aws/amazonlinux/amazonlinux:2

ARG NB_USER="sagemaker-user"
ARG NB_UID="1000"
ARG NB_GID="100"
RUN yum install --assumeyes python3 shadow-utils && \
    useradd --create-home --shell /bin/bash --gid "${NB_GID}" --uid ${NB_UID} ${NB_USER} && \
    yum clean all && \
    python3 -m pip install jupyterlab

RUN python3 -m pip install --upgrade pip

RUN python3 -m pip install --upgrade urllib3==1.26.6

USER ${NB_UID}
CMD jupyter lab --ip 0.0.0.0 --port 8888 \
  --ServerApp.base_url="/jupyterlab/default" \
  --ServerApp.token='' \
  --ServerApp.allow_origin='*'


            

Use the following Dockerfile template to create an Amazon SageMaker Distribution Image:

FROM public.ecr.aws/sagemaker/sagemaker-distribution:latest-cpu
ARG NB_USER="sagemaker-user"
ARG NB_UID=1000
ARG NB_GID=100

ENV MAMBA_USER=$NB_USER

USER root

RUN apt-get update
RUN micromamba install sagemaker-inference --freeze-installed --yes --channel conda-forge --name base

USER $MAMBA_USER

ENTRYPOINT ["jupyter-lab"]
CMD ["--ServerApp.ip=0.0.0.0", "--ServerApp.port=8888", "--ServerApp.allow_origin=*", "--ServerApp.token=''", "--ServerApp.base_url=/jupyterlab/default"]                
            

Step 2: Build the Dockerfile

In the same directory as your Dockerfile, build your image using the following command:

docker build -t username/imagename:tag your-account-id.dkr.ecr.AWS Region.amazonaws.com/your-repository-name:tag                    
                

Important

Your image must be tagged in the following format: 123456789012.dkr.ecr.your-region.amazonaws.com/your-repository-name:tag

You won’t be able to push it to an Amazon Elastic Container Registry repository otherwise.

Step 3: Push the image to the Amazon Elastic Container Registry repository

After you’ve built your image, log in to your Amazon ECR repository using the following command:

aws ecr get-login-password --region AWS Region | docker login --username AWS --password-stdin 123456789012.dkr.ecr.AWS Region.amazonaws.com                  
                

After you’ve logged in, push your Dockerfile using the following command:

docker push 123456789012.dkr.ecr.AWS Region.amazonaws.com/your-repository-name:tag
                

Step 4: Attach image to the Amazon SageMaker domain of your users

After you’ve pushed the image, you must access it from your Amazon SageMaker domain. Use the following procedure to attach the image to a SageMaker domain:

1. Open the SageMaker console.

2. Under Admin configurations, choose domains.

3. From the list of domains, select a domain.

4. Open the Environment tab.

5. For Custom images for personal Studio apps, choose Attach image.

6. Specify the image source.

7. Choose Next.

8. Choose Submit.

Your users can now select the image that you’ve attached to their Domain from their JupyterLab space.