# How to bring your own image
The following pages will provide instructions on how to bring your own custom image. Ensure that the following prerequisites are satisfied before continuing.
## Prerequisites
You will need to complete the following prerequisites to bring your own image to Amazon SageMaker AI.
+ 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/cli-chap-getting-started.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/AmazonECR/latest/userguide/ecr_managed_policies.html) in the *Amazon ECR User Guide*.
+ An AWS Identity and Access Management role that has the [AmazonSageMakerFullAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AmazonSageMakerFullAccess) policy attached.
**Topics**
+ [Prerequisites](#studio-updated-byoi-how-to-prerequisites)
+ [Create a custom image and push to Amazon ECR](studio-updated-byoi-how-to-prepare-image.md)
+ [Attach your custom image to your domain](studio-updated-byoi-how-to-attach-to-domain.md)
+ [Update container configuration](studio-updated-byoi-how-to-container-configuration.md)
# Create a custom image and push to Amazon ECR
This page provides instructions on how to create a local Dockerfile, build the container image, and add it to Amazon Elastic Container Registry (Amazon ECR).
**Note**
In the following examples, the tags are not specified, and the tag `latest` is applied by default. If you would like to specify a tag, you will need to append `:tag` to end of the image names. For more information, see [docker image tag](https://docs.docker.com/reference/cli/docker/image/tag/) in the *Docker documentation*.
**Topics**
+ [Create a local Dockerfile and build the container image](#studio-updated-byoi-how-to-create-local-dockerfile)
+ [Add a Docker image to Amazon ECR](#studio-updated-byoi-add-container-image)
## Create a local Dockerfile and build the container image
Use the following instructions to create a Dockerfile with your desired software and dependencies.
**To create your Dockerfile**
1. First set your variables for the AWS CLI commands that follow.
```
LOCAL_IMAGE_NAME=local-image-name
```
`local-image-name` is the name of the container image on your local device, that you define here.
1. Create a text-based document, named `Dockerfile`, that meet the specifications in [Custom image specifications](studio-updated-byoi-specs.md).
`Dockerfile` examples for supported applications can be found in [Dockerfile samples](studio-updated-byoi-specs.md#studio-updated-byoi-specs-dockerfile-templates).
**Note**
If you are bringing your own image to SageMaker Unified Studio, you will need to follow the [Dockerfile specifications](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html) in the *Amazon SageMaker Unified Studio User Guide*.
`Dockerfile` examples for SageMaker Unified Studio can be found in [Dockerfile example](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html#byoi-specifications-example) in the *Amazon SageMaker Unified Studio User Guide*.
1. In the directory containing your `Dockerfile`, build the Docker image using the following command. The period (`.`) specifies that the `Dockerfile` should be in the context of the build command.
```
docker build -t ${LOCAL_IMAGE_NAME} .
```
After the build completes, you can list your container image information with the following command.
```
docker images
```
1. (Optional) You can test your image by using the following command.
```
docker run -it ${LOCAL_IMAGE_NAME}
```
In the output you will find that your server is running at a URL, like `http://127.0.0.1:8888/...`. You can test the image by copying the URL into the browser.
If this does not work, you may need to include `-p port:port` in the docker run command. This option maps the exposed port on the container to a port on the host system. For more information about docker run, see the [Running containers](https://docs.docker.com/engine/containers/run/) in the *Docker documentation*.
Once you have verified that the server is working, you can stop the server and shut down all kernels before continuing. The instructions are viewable the output.
## Add a Docker image to Amazon ECR
To add a container image to Amazon ECR, you will need to do the following.
+ Create an Amazon ECR repository.
+ Log in to your default registry.
+ Push the image to the Amazon ECR repository.
**Note**
The Amazon ECR repository must be in the same AWS Region as the domain you are attaching the image to.
**To build and push the container image to Amazon ECR**
1. First set your variables for the AWS CLI commands that follow.
```
ACCOUNT_ID=account-id
REGION=aws-region
ECR_REPO_NAME=ecr-repository-name
```
+ `account-id` is your account ID. You can find this at the top right of any AWS console page. For example, the [SageMaker AI console](https://console.aws.amazon.com/sagemaker).
+ `aws-region` is the AWS Region of your Amazon SageMaker AI domain. You can find this at the top right of any AWS console page.
+ `ecr-repository-name` is the name of your Amazon Elastic Container Registry repository, that you define here. To view your Amazon ECR repositories, see the [Amazon ECR console](https://console.aws.amazon.com/ecr).
1. Log in to Amazon ECR and sign in to Docker.
```
aws ecr get-login-password \
--region ${REGION} | \
docker login \
--username AWS \
--password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com
```
On a successful authentication, you will receive a succeeded log in message.
**Important**
If you receive an error, you may need to install or upgrade to the latest version of the AWS CLI. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*.
1. Tag the image in a format compatible with Amazon ECR, to push to your repository.
```
docker tag \
${LOCAL_IMAGE_NAME} \
${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/${ECR_REPO_NAME}
```
1. Create an Amazon ECR repository using the AWS CLI. To create the repository using the Amazon ECR console, see [Creating an Amazon ECR private repository to store images](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html).
```
aws ecr create-repository \
--region ${REGION} \
--repository-name ${ECR_REPO_NAME}
```
1. Push the image to your Amazon ECR repository. You can also tag the Docker image.
```
docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/${ECR_REPO_NAME}
```
Once the image has been successfully added to your Amazon ECR repository, you can view it in the [Amazon ECR console](https://console.aws.amazon.com/ecr).
# Attach your custom image to your domain
This page provides instructions on how to attach your custom image to your domain. Use the following procedure to use the Amazon SageMaker AI console to navigate to your domain and start the **Attach image** process.
The following instructions assume that you have pushed an image to a Amazon ECR repository in the same AWS Region as your domain. If you have not already done so, see [Create a custom image and push to Amazon ECR](studio-updated-byoi-how-to-prepare-image.md).
When you choose to attach an image, you will have two options:
+ Attach a **New image**: This option will create an image and image version in your SageMaker AI image store and then attach it to your domain.
**Note**
If you are continuing the BYOI process, from [Create a custom image and push to Amazon ECR](studio-updated-byoi-how-to-prepare-image.md), use the **New image** option.
+ Attach an **Existing image**: If you have already created your intended custom image in the SageMaker AI image store, use this option. This option attaches an existing custom image to your domain. To view your custom images in the SageMaker AI image store, see [View custom image details (console)](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console).
------
#### [ New image ]
**To attach a new image to your domain**
1. Open the [SageMaker AI console](https://console.aws.amazon.com/sagemaker).
1. Expand the **Admin configurations** section, if not already done so.
1. Under **Admin configurations**, choose **Domains**.
1. From the list of **Domains**, select the domain you want to attach the image to.
**Note**
If you are attaching the image to a SageMaker Unified Studio project and you need clarification on which domain to use, see [View the SageMaker AI domain details associated with your project](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/view-project-details.html#view-project-details-smai-domain).
1. Open the **Environment** tab.
1. In the **Custom images for personal Studio apps** section, choose **Attach image**.
1. For the **Image source**, choose **New image**.
1. Include your Amazon ECR image URI. The format is as follows.
```
account-id.dkr.ecr.aws-region.amazonaws.com/repository-name:tag
```
1. To obtain your Amazon ECR image URI, navigate to your [Amazon ECR private repositories](https://console.aws.amazon.com/ecr/private-registry/repositories) page.
1. Choose your repository name link.
1. Choose the **Copy URI** icon that corresponds to your image version (**Image tag**).
1. Follow the rest of the instructions to attach your custom image.
**Note**
Ensure that you are using the application type consistent with your `Dockerfile`. For more information, see [Dockerfile samples](studio-updated-byoi-specs.md#studio-updated-byoi-specs-dockerfile-templates).
Once the image has been successfully attached to your domain, you will be able to view it in the **Environment** tab.
------
#### [ Existing image ]
**To attach an existing image to your domain**
1. Open the [SageMaker AI console](https://console.aws.amazon.com/sagemaker).
1. Expand the **Admin configurations** section, if not already done so.
1. Under **Admin configurations**, choose **Domains**.
1. From the list of **Domains**, select the domain you want to attach the image to.
**Note**
If you are attaching the image to a SageMaker Unified Studio project and you need clarification on which domain to use, see [View the SageMaker AI domain details associated with your project](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/view-project-details.html#view-project-details-smai-domain).
1. Open the **Environment** tab.
1. In the **Custom images for personal Studio apps** section, choose **Attach image**.
1. For the **Image source**, choose **Existing image**.
1. Choose an existing image and image version from the SageMaker AI image store.
If you are unable to view your image version, you may need to create an image version. For more information, see [View custom image details (console)](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console).
1. Follow the rest of the instructions to attach your custom image.
**Note**
Ensure that you are using the application type consistent with your `Dockerfile`. For more information, see [Dockerfile samples](studio-updated-byoi-specs.md#studio-updated-byoi-specs-dockerfile-templates).
Once the image has been successfully attached to your domain, you will be able to view it in the **Environment** tab.
------
Once your image has been successfully attached to your domain, the domain users can choose the image for their application. For more information, see [Launch a custom image in Studio](studio-updated-byoi-how-to-launch.md).
**Note**
If you have attached a custom image to your SageMaker Unified Studio project, you will need to launch the application from within SageMaker Unified Studio. For more information, see [Launch your custom image](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-launch-custom-image.html) in the *Amazon SageMaker Unified Studio User Guide*.
# Update container configuration
You can bring custom Docker images into your machine learning workflows. A key aspect of customizing these images is configuring the container configurations, or [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html). The following page provides an example on how to configure your `ContainerConfig`.
An entrypoint is the command or script that runs when the container starts. Custom entrypoints enable you to set up your environment, initialize services, or perform any necessary setup before your application launches.
This example provides instructions on how to configure a custom entrypoint, for your JupyterLab application, using the AWS CLI. This example assumes that you have already created a custom image and domain. For instructions, see [Attach your custom image to your domain](studio-updated-byoi-how-to-attach-to-domain.md).
1. First set your variables for the AWS CLI commands that follow.
```
APP_IMAGE_CONFIG_NAME=app-image-config-name
ENTRYPOINT_FILE=entrypoint-file-name
ENV_KEY=environment-key
ENV_VALUE=environment-value
REGION=aws-region
DOMAIN_ID=domain-id
IMAGE_NAME=custom-image-name
IMAGE_VERSION=custom-image-version
```
+ `app-image-config-name` is the name of your application image configuration.
+ `entrypoint-file-name` is the name of your container's entrypoint script. For example, `entrypoint.sh`.
+ `environment-key` is the name of your environment variable.
+ `environment-value` is the value assigned to your environment variable.
+ `aws-region` is the AWS Region of your Amazon SageMaker AI domain. You can find this at the top right of any AWS console page.
+ `domain-id` is your domain ID. To view your domains, see [View domains](domain-view.md).
+ `custom-image-name` is the name of your custom image. To view your custom image details, see [View custom image details (console)](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console).
If you followed the instructions in [Attach your custom image to your domain](studio-updated-byoi-how-to-attach-to-domain.md), you may want to use the same image name you used in that process.
+ `custom-image-version` is the version number of your custom image. This should be an integer, representing the version of your image. To view your custom image details, see [View custom image details (console)](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console).
1. Use the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateAppImageConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateAppImageConfig.html) API to create an image configuration.
```
aws sagemaker create-app-image-config \
--region ${REGION} \
--app-image-config-name "${APP_IMAGE_CONFIG_NAME}" \
--jupyter-lab-app-image-config "ContainerConfig = {
ContainerEntrypoint = "${ENTRYPOINT_FILE}",
ContainerEnvironmentVariables = {
"${ENV_KEY}"="${ENV_VALUE}"
}
}"
```
1. Use the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html) API to update the default settings for your domain. This will attach the custom image as well as the application image configuration.
```
aws sagemaker update-domain \
--region ${REGION} \
--domain-id "${DOMAIN_ID}" \
--default-user-settings "{
\"JupyterLabAppSettings\": {
\"CustomImages\": [
{
\"ImageName\": \"${IMAGE_NAME}\",
\"ImageVersionNumber\": ${IMAGE_VERSION},
\"AppImageConfigName\": \"${APP_IMAGE_CONFIG_NAME}\"
}
]
}
}"
```