Skip to main content

​
vers build

Build custom rootfs images from Dockerfiles for your Vers environment.

​
Synopsis

vers build                           # Build using vers.toml configuration
vers build --rootfs custom-name     # Override rootfs name
vers build --dockerfile ./custom.dockerfile  # Use different Dockerfile

​
Description

The build command creates custom rootfs (root filesystem) images by packaging your project directory and building it with Docker. This lets you create specialized environments with pre-installed dependencies and configurations.

​
Requirements

​
vers.toml Configuration File

You need a vers.toml file in your current directory. If it doesn’t exist, the command will use default values but show a warning. Complete vers.toml structure: 
[machine]
mem_size_mib = 512          # Memory size in MiB
vcpu_count = 1              # Number of virtual CPUs
fs_size_cluster_mib = 1024  # Cluster filesystem size in MiB  
fs_size_vm_mib = 512        # VM filesystem size in MiB

[rootfs]
name = "default"            # Name for your rootfs image

[builder]
name = "docker"             # Builder type ("docker" or "none")
dockerfile = "Dockerfile"   # Path to Dockerfile

[kernel]
name = "default.bin"        # Kernel name

​
Docker Builder Required

The builder must be set to "docker". Other values are not supported: 
[builder]
name = "docker"             # Only "docker" is supported
dockerfile = "Dockerfile"   # Path to your Dockerfile
If you set name = "none", the build will be skipped: 
vers build
# Output: Builder is set to 'none'; skipping

​
Dockerfile Required

You must have a Dockerfile at the specified path (default: ./Dockerfile): 
FROM ubuntu:20.04
RUN apt-get update && apt-get install -y python3 python3-pip
COPY . /app
WORKDIR /app
RUN pip3 install -r requirements.txt

​
Restrictions

​
Cannot Use “default” Name

You cannot build a rootfs named “default”: 
[rootfs]
name = "default"  # ❌ This will cause an error
Error message: 
If you're trying to upload a custom rootfs, please specify a new name for rootfs.name in vers.toml. Otherwise, set builder.name to 'none'.
Fix: Use a custom name: 
[rootfs]
name = "my-custom-app"  # ✅ This works

​
Build Process

  1. Configuration Loading: Loads vers.toml or uses defaults
  2. Validation: Checks builder type and Dockerfile existence
  3. Archive Creation: Creates tar archive of current directory (excludes .vers/ and vers.toml)
  4. Upload: Uploads archive to Vers platform with 10-minute timeout
  5. Docker Build: Platform builds your Dockerfile
  6. Registration: Rootfs becomes available for VM creation
Build output: 
vers build
Warning: vers.toml not found, using default configuration
Creating tar archive of working directory...
Uploading rootfs archive as 'my-app'...
Successfully uploaded rootfs: my-app

​
Command-Line Flags

Flags override values from vers.toml:

​
--rootfs <name>

Override the rootfs name: 
vers build --rootfs my-custom-name
# Overrides [rootfs] name = "..." from vers.toml

​
--dockerfile <path>

Override the Dockerfile path: 
vers build --dockerfile containers/Dockerfile.prod
# Overrides [builder] dockerfile = "..." from vers.toml

​
Examples

​
Basic Build with vers.toml

# vers.toml
[rootfs]
name = "python-app"

[builder]  
name = "docker"
dockerfile = "Dockerfile"

vers build
# Uses configuration from vers.toml

​
Override Rootfs Name

vers build --rootfs python-app-v2
# Uses "python-app-v2" instead of name from vers.toml

​
Development vs Production Builds

# Development build
vers build --rootfs app-dev --dockerfile Dockerfile.dev

# Production build  
vers build --rootfs app-prod --dockerfile Dockerfile.prod

​
Node.js Application

# vers.toml
[rootfs]
name = "node-backend"

[builder]
name = "docker"
dockerfile = "Dockerfile"

# Dockerfile
FROM node:16
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

vers build

​
File Exclusions

The build automatically excludes these files from the tar archive:
  • .vers/ directory (Vers internal data)
  • vers.toml file (configuration file)
  • The temporary tar file itself
Everything else in your current directory gets included in the build context.

​
Build Timeout

Builds have a 10-minute timeout. If your build takes longer, it will fail with a timeout error.

​
Using Built Images

After building, use your custom rootfs by updating vers.toml: 
[rootfs]
name = "my-custom-app"  # Your built image name
Then start your environment: 
vers up

​
Error Scenarios

​
Missing Dockerfile

vers build
# Error: Dockerfile 'Dockerfile' not found in current directory
Solution: Create the Dockerfile or use --dockerfile to specify the correct path.

​
Unsupported Builder

vers build
# Error: unsupported builder: custom (only 'docker' is currently supported)
Solution: Set builder.name = "docker" in vers.toml.

​
Protected Name

vers build
# Error: If you're trying to upload a custom rootfs, please specify a new name for rootfs.name in vers.toml. Otherwise, set builder.name to 'none'.
Solution: Change rootfs.name to something other than “default”.

​
Configuration File Issues

vers build
# Error: failed to load configuration: error parsing vers.toml: ...
Solution: Fix the TOML syntax in your vers.toml file.

​
See Also

  • vers rootfs - Manage existing rootfs images
  • vers up - Start VMs using your built images
  • vers init - Create a new vers.toml configuration file