Build Templates

Once you have written your Dockerfile, use the ve CLI to build and push the template to Vibengine. This page covers the build process, configuration options, and troubleshooting.

Prerequisites

Before building, make sure:

• The ve CLI is installed and you are logged in
• Your VE_API_KEY environment variable is set
• Docker is running on your machine
• You have a valid ve.toml and Dockerfile in your template directory

Building a Template

Navigate to your template directory (where ve.toml lives) and run:

ve template build

This command:

1. Reads the ve.toml to determine the template ID and Dockerfile path
2. Sends the build context (Dockerfile and any local files) to the Vibengine build service
3. Builds the Docker image on Vibengine infrastructure
4. Registers the new image as a usable sandbox template

Build Output

During the build you will see Docker build logs streamed to your terminal:

Building template my-data-science...
Uploading build context... done (2.3 KB)

Step 1/5 : FROM vibengine/base:latest
 ---> a1b2c3d4e5f6
Step 2/5 : RUN apt-get update && apt-get install -y python3 python3-pip
 ---> Running in f6e5d4c3b2a1
...
Step 5/5 : WORKDIR /home/user
 ---> Running in 6f5e4d3c2b1a

Successfully built 8a7b6c5d4e3f

Template my-data-science built successfully!

Build Configuration

The ve.toml file controls how your template is built:

# Template identifier — must be unique within your account
id = "my-data-science"

# Path to the Dockerfile (relative to ve.toml)
dockerfile = "Dockerfile"

# Optional: specify a build tag
# tag = "v1.2.0"

Custom Dockerfile Path

If your Dockerfile is not in the same directory as ve.toml, specify the path:

id = "my-template"
dockerfile = "docker/Dockerfile.prod"

Build with a Tag

You can tag a specific build for versioning:

ve template build --tag v1.0.0

Without a tag, the build is automatically tagged as latest. See Template Tags for more on versioning.

Viewing Past Builds

List all builds for a template:

ve template list

This shows every template along with its tags and last build time.

Build Caching

Vibengine caches Docker layers between builds. If you only change a later step in your Dockerfile, earlier layers are reused, making rebuilds significantly faster.

Build Context

The entire directory containing your ve.toml is sent as the build context. This means:

• Any files referenced by COPY or ADD in your Dockerfile must be in this directory or its subdirectories.
• Large files in the directory will slow down the upload. Use a .dockerignore file to exclude unnecessary files.

Example .dockerignore:

node_modules/
.git/
*.log
.env

Troubleshooting Build Failures

Authentication Error

Error: unauthorized — invalid or expired API key

Verify your API key is set correctly:

export VE_API_KEY=your_api_key_here
ve auth verify

Dockerfile Not Found

Error: could not find Dockerfile at ./Dockerfile

Check that ve.toml points to the correct Dockerfile path and that the file exists.

Package Installation Fails

If apt-get install or pip install fails during build, the most common causes are:

• Missing dependencies — Some Python packages need system libraries. Add them with apt-get install before pip install.
• Network issues — Transient network failures during build. Simply retry with ve template build.
• Version conflicts — Pin specific versions to avoid incompatible dependency resolutions.

Image Too Large

Tips to reduce image size:

# Clean apt cache
RUN apt-get update && apt-get install -y ... \
    && rm -rf /var/lib/apt/lists/*

# Use --no-cache-dir with pip
RUN pip3 install --no-cache-dir package1 package2

# Remove build tools after compilation
RUN apt-get install -y build-essential \
    && pip3 install some-package \
    && apt-get purge -y build-essential \
    && apt-get autoremove -y

Base Image Not Found

Error: failed to pull vibengine/base:latest

Make sure Docker is running and has network access. If you are behind a proxy, configure Docker to use it.

Rebuilding a Template

To update a template, edit the Dockerfile and run ve template build again. The new build replaces the latest tag by default. Previous tagged versions remain available.

# Edit your Dockerfile, then rebuild
ve template build

Deleting a Template

To permanently remove a template and all its versions:

ve template delete my-data-science

This action cannot be undone. Any code referencing this template ID will fail to create sandboxes.

Next Steps

• Template Tags — Version your templates with tags
• Template Examples — Browse complete working examples