# Bring your own image (BYOI)
An image is a file that identifies the kernels, language packages, and other dependencies required to run your applications. It includes:
+ Programming languages (like Python or R)
+ Kernels
+ Libraries and packages
+ Other necessary software
Amazon SageMaker AI Distribution ([https://gallery.ecr.aws/sagemaker/sagemaker-distribution](https://gallery.ecr.aws/sagemaker/sagemaker-distribution)) is a set of Docker images that include popular frameworks and packages for machine learning, data science, and visualization.
You can also create your own custom image, using an Amazon SageMaker AI Distribution image as a base image, to bring your own image (BYOI). You may want to BYOI when:
+ You need a specific version of a programming language or library
+ You want to include custom tools or packages
+ You're working with specialized software not available in the standard images
**Topics**
+ [
# Dockerfile specifications
](byoi-specifications.md)
+ [
# How to BYOI
](byoi-how-to.md)
+ [
# Launch your custom image in Amazon SageMaker Unified Studio
](byoi-launch-custom-image.md)
+ [
# Speed up container startup with SOCI
](byoi-soci-indexing.md)
+ [
# Detach and clean up custom image resources
](byoi-clean-up.md)
# Dockerfile specifications
To bring your own image (BYOI), ensure that the following specifications are satisfied when you create your `Dockerfile`.
+ **Base image specifications**: You must use one of the base images from Amazon SageMaker AI Distribution ([https://gallery.ecr.aws/sagemaker/sagemaker-distribution](https://gallery.ecr.aws/sagemaker/sagemaker-distribution)), with the following specifications. These contain important extensions that are required to execute an image on Amazon SageMaker Unified Studio.
+ The base image must be `FROM public.ecr.aws/sagemaker/sagemaker-distribution:version`. You can copy the Image URI of an image from the Image tags tab in [https://gallery.ecr.aws/sagemaker/sagemaker-distribution](https://gallery.ecr.aws/sagemaker/sagemaker-distribution).
+ The chosen image `version` must be greater or equal to the following.
+ For CPU, `2.6-cpu`
+ For GPU: `2.6-gpu`
+ Follow the [Custom image specifications](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-byoi-specs.html) in the *SageMaker AI Developer Guide*.
## Dockerfile example
The following is an example `Dockerfile` that meets the above criteria. The `version` in this example must satisfy the specification above.
**Note**
Adding `ENTRYPOINT` in the `Dockerfile` will not work as expected. If you would like to configure a custom entrypoint, you will need to update your [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html). For an example, see [Update container configuration](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-byoi-how-to-container-configuration.html) in the *SageMaker AI Developer Guide*.
```
FROM public.ecr.aws/sagemaker/sagemaker-distribution:version
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
```
# How to BYOI
When you bring your own image (BYOI) to Amazon SageMaker Unified Studio, you attach a custom image to an Amazon SageMaker Unified Studio project. The following page provides instructions on how to bring your custom image to your Amazon SageMaker Unified Studio project.
**Topics**
+ [
## Prerequisites
](#byoi-how-to-prerequisites)
+ [
## Step 1: Create your custom image
](#byoi-how-to-step-1-create-custom-image)
+ [
## Step 2: Get the SageMaker AI domain name associated with your Amazon SageMaker Unified Studio project
](#byoi-how-to-step-2-get-domain-name)
+ [
## Step 3: Attach your custom image using the SageMaker AI domain
](#byoi-how-to-step-3-attach-custom-image)
+ [
## Step 4: Access your custom image in Amazon SageMaker Unified Studio
](#byoi-how-to-step-4-access-custom-image)
## Prerequisites
You will need to complete the following prerequisites to bring your own image to Amazon SageMaker Unified Studio.
+ Create an Amazon SageMaker Unified Studio project. For more information, see [Create a new project](create-new-project.md).
+ Set up the Docker application. For more information, see [Get started](https://docs.docker.com/get-started/) in the *Docker documentation*.
+ Install the latest AWS CLI by following the steps in [Getting started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide for Version 2*.
+ Permissions to access the Amazon Elastic Container Registry (Amazon ECR) service. For more information, see [Amazon ECR Managed Policies](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the *Amazon ECR User Guide*.
+ An AWS Identity and Access Management role that has the [AmazonSageMakerFullAccess](https://docs.aws.amazon.com/sagemaker/latest/dg/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonSageMakerFullAccess) policy attached.
## Step 1: Create your custom image
**Important**
Ensure that you are using the [Dockerfile specifications](byoi-specifications.md) in the following instructions.
Follow the steps in [Create a custom image and push to Amazon ECR](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-byoi-how-to-prepare-image.html) in the *SageMaker AI Developer Guide*.
## Step 2: Get the SageMaker AI domain name associated with your Amazon SageMaker Unified Studio project
An associated SageMaker AI domain is created when you create a Amazon SageMaker Unified Studio project. You will need the SageMaker AI domain name before proceeding to the next step. For instructions, see [View the SageMaker AI domain details associated with your project](view-project-details.md#view-project-details-smai-domain).
## Step 3: Attach your custom image using the SageMaker AI domain
To attach your custom image to your Amazon SageMaker Unified Studio project, you must attach your custom image to your SageMaker AI domain. Follow the steps in [Attach your custom image to your domain](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-byoi-how-to-attach-to-domain.html) in the *SageMaker AI Developer Guide*, using the SageMaker AI domain obtained from above.
## Step 4: Access your custom image in Amazon SageMaker Unified Studio
Once your custom image is attached to your Amazon SageMaker Unified Studio project, the users with access to your project can access it. For instructions on how users can access the custom images, see [Launch your custom image in Amazon SageMaker Unified Studio](byoi-launch-custom-image.md).
# Launch your custom image in Amazon SageMaker Unified Studio
The following section provides information on how to launch your custom image in Amazon SageMaker Unified Studio. If you have not already created a custom image, see [How to BYOI](byoi-how-to.md).
**To launch your custom image in Amazon SageMaker Unified Studio**
1. Navigate to Amazon SageMaker Unified Studio using the URL from your admin and log in using your IAM Identity Center (SSO) or AWS credentials. For more information, see [Access Amazon SageMaker Unified Studio](getting-started-access-the-portal.md).
1. Navigate to the Amazon SageMaker Unified Studio home page by choosing the icon located at the top left corner of the page.
1. You can choose to create a project or choose an existing one.
1. Once you choose a project you will be taken to the **Project overview** page.
1. On the **Project overview** page, open your notebook. To do so:
1. Choose **New** to expand the dropdown menu, located at the top right of the page.
1. Choose **Notebook**, then continue with the following steps.
1. Once your notebook is open, choose **Configure space**, located at the top right of the page.
1. In the **Configure space** section, you can choose the image from the **Image** dropdown menu.
1. After you have verified the settings, choose **Save and restart**.
Once completed, this will start a new JupyterLab instance with the custom image.
# Speed up container startup with SOCI
SOCI (Seekable Open Container Initiative) indexing enables lazy loading of custom container images in Amazon SageMaker Unified Studio or [Amazon SageMaker Unified Studio](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated.html). SOCI significantly reduces startup times by roughly 30-70% for your custom [Bring your own image (BYOI)](byoi.md) containers. Latency improvement varies depending on the size of the image, hosting instance availability, and other application dependencies. SOCI creates an index that allows containers to launch with only necessary components, fetching additional files on-demand as needed.
SOCI addresses slow container startup times, that interrupt iterative machine learning (ML) development workflows, for custom images. As ML workloads become more complex, container images have grown larger, creating startup delays that hamper development cycles.
For more information on SOCI indexing and how to use them, see [Speed up container startup with SOCI](https://docs.aws.amazon.com/sagemaker/latest/dg/soci-indexing.html) in the *Amazon SageMaker Unified Studio Developer Guide*.
# Detach and clean up custom image resources
An associated SageMaker AI domain is created when you create an Amazon SageMaker Unified Studio project. You will need the SageMaker AI domain details to detach and clean up your custom image resources. For instructions, see [View the SageMaker AI domain details associated with your project](view-project-details.md#view-project-details-smai-domain).
Follow the instructions in [Detach and clean up custom image resources](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-updated-byoi-how-to-detach-from-domain.html) in the *Amazon SageMaker AI Developer Guide*.