Base Image

How to define a base image for your template

Creating template

When creating a template, you can specify options:

Typescript

const template = Template({
  fileContextPath: ".", // Custom file context path
  fileIgnorePatterns: [".git", "node_modules"], // File patterns to ignore
});

File ignoring: The SDK automatically reads .dockerignore files and combines them with your fileIgnorePatterns (TypeScript) or file_ignore_patterns (Python). Files matching these patterns are excluded from uploads and hash calculations.

Defining base image

Choose from predefined base images or use custom ones:

Typescript

// Predefined base images
template.fromUbuntuImage("lts"); // ubuntu:lts
template.fromUbuntuImage("22.04"); // ubuntu:22.04
template.fromDebianImage("slim"); // debian:slim
template.fromDebianImage("bullseye"); // debian:bullseye
template.fromPythonImage("3.13"); // python:3.13
template.fromPythonImage("3.11"); // python:3.11
template.fromNodeImage("lts"); // node:lts
template.fromNodeImage("20"); // node:20

// Custom base image
template.fromImage("custom-image:latest");

// Use default E2B base image
template.fromBaseImage(); // e2bdev/base

// Parse existing Dockerfile
const dockerfileContent = `
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
ENV NODE_ENV=production`;

template.fromDockerfile(dockerfileContent);

You can only call base image methods once per template. Subsequent calls will throw an error.

Parsing existing Dockerfiles

Convert existing Dockerfiles to template format using fromDockerfile():

Typescript

const dockerfileContent = `
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
WORKDIR /app
COPY . .
ENV NODE_ENV=production
ENV PORT=3000
USER appuser`;

const template = Template()
  .fromDockerfile(dockerfileContent)
  .setStartCmd("npm start", waitForTimeout(5_000));

Dockerfile instructions support

Instruction	Supported	Behavior
FROM		Sets base image
RUN		Converts to runCmd() / run_cmd()
COPY / ADD		Converts to copy()
WORKDIR		Converts to setWorkdir() / set_workdir()
USER		Converts to setUser() / set_user()
ENV		Converts to setEnvs() / set_envs(); supports both ENV key=value and ENV key value formats
CMD / ENTRYPOINT		Converts to setStartCmd() / set_start_cmd() with 20 seconds timeout as ready command
EXPOSE		Skipped (not supported)
VOLUME		Skipped (not supported)

Multi-stage Dockerfiles are not supported.

Login to private registries

If your base image is hosted in a private registry, you can provide credentials using the following helpers:

• General registry
• GCP Artifact Registry
• AWS ECR

General Registry

Typescript

Template().fromImage('ubuntu:22.04', {
  username: 'user',
  password: 'pass',
})

GCP Artifact Registry

Typescript

// From file path
Template().fromGCPRegistry('ubuntu:22.04', {
  serviceAccountJSON: './service_account.json',
})

// From object
Template().fromGCPRegistry('ubuntu:22.04', {
  serviceAccountJSON: { project_id: '123', private_key_id: '456' },
})

AWS ECR

Typescript

Template().fromAWSRegistry('ubuntu:22.04', {
  accessKeyId: '123',
  secretAccessKey: '456',
  region: 'us-west-1',
})