Skip to main content

Create Instances with Your Own Container Image

The platform is container-native, giving you the full flexibility and performance of containers for AI/ML workloads — without any infrastructure overhead.

You can launch instances using your own custom container image, allowing you to tailor the environment to your exact needs by adding specific packages, libraries, and configurations.

Why use a custom image?

Packages installed directly in a running instance are not fully persistent — only the /data and /home/jovyan directories are preserved on restart. Using a custom image guarantees your environment is consistent and reproducible every time your instance starts.

Overview​

Setting up a custom container involves three stages:

StepDescription
BuildCreate a Docker image with your required packages and environment
PushUpload the image to the E2E Container Registry
LaunchStart an instance using your custom image

Step 1: Build a Container Image​

We recommend extending our pre-configured base images, as they are already optimized for platform compatibility and GPU support.

Requirements​

Before building, ensure your image meets the following:

  • Platform: Image must be built for linux/amd64
  • Registry: Image must be available in a container registry
  • Jupyter Lab: Container must expose port 8888 running Jupyter Lab

To target the correct platform, specify it in your Dockerfile:

FROM --platform=linux/amd64 <base-image>

Or pass it as a build flag:

docker build --platform=linux/amd64 ...

This is the most reliable and reproducible approach. Pick a base image that matches your framework, add your dependencies, and build.

FROM --platform=linux/amd64 aimle2e/ubuntu-cuda-jupyter:22.04-12.2.2

# Install your required packages
# RUN pip install -r requirements.txt
docker build --platform linux/amd64 -t my-repo/tir-cuda:12.2.2-ubuntu22.04-01 .

Option B: Patch a Running Container Interactively​

Prefer installing packages manually? You can run a base container, install what you need inside it, and save it as a new image.

  1. Start the base image:

    docker run --platform=linux/amd64 -d <base-image>

  2. Enter the running container:

    docker exec -it <container_id> /bin/bash

    Install your required packages inside the container, then type exit to leave.

  3. Save your changes as a new image:

    docker commit <container_id> <your-image-name:tag>

  4. Push the image to your registry — continue to Step 2.

Option C: Use the Image Builder Utility​

Already have a custom image that isn't platform-compatible? Use the Image Builder Utility to automatically patch it for instance use.

git clone https://github.com/tire2e/notebook-image-builder.git
cd notebook-image-builder/
./generate_image.sh -b my-trainer:latest -i tir-my-trainer -t v1

To auto-push to the E2E Container Registry, add the -P flag:

./generate_image.sh -b my-trainer:latest -i tir-my-trainer -t v1 -P

Use -u <username> if you are not already logged in to the registry.


info

If you used -P to auto-push via the Image Builder, skip Step 2 — your image is already in the registry.

Which Option Is Right for Me?​

ScenarioRecommended Option
Starting fresh, want a clean and reproducible setupOption A – Dockerfile
Prefer installing packages manually and saving the resultOption B – Patch a running container
Have an existing custom image that needs compatibility fixesOption C – Image Builder Utility

Step 2: Push the Container Image​

2.1 Set Up Registry Integration​

  1. Log in to the AI platform and select your Project.
  2. Navigate to Integrations → E2E Container Registry.
  3. Click Create E2E Registry.
  4. Provide a Namespace (e.g., my-workspace) and a Username Prefix.
  5. Once created, your registry is ready to receive images.

2.2 Log In to the Registry Locally​

docker login registry.e2enetworks.net

Enter your platform credentials when prompted.

2.3 Tag and Push Your Image​

First, tag your image with the full registry path:

docker tag my-custom-image:v1 registry.e2enetworks.net/<your-namespace>/my-custom-image:v1

Then push it to the registry:

docker push registry.e2enetworks.net/<your-namespace>/my-custom-image:v1

Replace <your-namespace> with the namespace you created in Step 2.1.

tip

Your namespace-specific tag and push commands are also available directly in the dashboard under Commands.

Step 3: Launch an Instance with Your Custom Image​

  1. Go to the platform and click Create Instance.
  2. Under image selection, choose Custom Images.
  3. Set Image Type to Private.
  4. Select your Registry Namespace from the dropdown.
  5. Choose your pushed image and tag.
  6. Fill in the remaining instance details (hardware, storage, etc.) and click Launch.
  7. Once the instance is running, open Jupyter Lab or connect via SSH to verify your packages are available.

Troubleshooting​

IssueLikely CauseFix
Build fails with platform errorWrong architectureEnsure --platform=linux/amd64 is set
Push fails with auth errorNot logged in to registryRun docker login registry.e2enetworks.net
Packages missing after instance restartInstalled in live session, not in imageRebuild your image with those packages
Port error on launchPort 8888 not exposedEnsure your image runs Jupyter Lab on port 8888