vers config

Manage and understand Vers configuration files and settings.

Synopsis

# Configuration is managed through vers.toml files
# This reference explains the configuration system

Description

Vers uses TOML (Tom’s Obvious, Minimal Language) configuration files to define VM specifications, image settings, and build parameters. The primary configuration file is vers.toml, which controls how clusters and VMs are created and configured. While there’s no standalone vers config command, configuration management is integrated throughout the Vers CLI through file parsing, flag overrides, and default value systems.

Configuration File Structure

Complete vers.toml Example

[machine]
mem_size_mib = 2048           # VM memory allocation in MiB
vcpu_count = 4                # Number of virtual CPU cores
fs_size_cluster_mib = 8192    # Total cluster filesystem size in MiB
fs_size_vm_mib = 4096         # Individual VM filesystem size in MiB

[rootfs]
name = "ubuntu-dev"           # Base filesystem image name

[kernel]  
name = "vmlinux-5.15.bin"     # Kernel image file name

[builder]
name = "docker"               # Build system: "docker" or "none"
dockerfile = "Dockerfile"     # Dockerfile path for custom builds

Minimal Configuration

[machine]
mem_size_mib = 512

[rootfs]
name = "default"

Configuration Sections

[machine] Section

Controls VM hardware specifications and resource allocation:

Memory Configuration

mem_size_mib - RAM allocation per VM in mebibytes
Range - Typically 512-16384 MiB, depending on system capacity
Impact - Affects VM performance and system resource usage

[machine]
mem_size_mib = 1024    # 1 GB RAM per VM

CPU Configuration

vcpu_count - Number of virtual CPU cores per VM
Range - 1-16 cores typical, limited by host system
Impact - Affects parallel processing capability

[machine]
vcpu_count = 2         # 2 CPU cores per VM

Storage Configuration

fs_size_cluster_mib - Total storage allocated to cluster
fs_size_vm_mib - Storage allocated to individual VMs
Relationship - Cluster size must accommodate all VMs plus overhead

[machine]
fs_size_cluster_mib = 4096    # 4 GB total cluster storage
fs_size_vm_mib = 2048         # 2 GB per VM
# Allows room for ~2 VMs plus system overhead

[rootfs] Section

Defines the base filesystem image for VMs:

Image Selection

name - Identifier for the rootfs image
“default” - Uses system default image
Custom names - References uploaded or built images

[rootfs]
name = "ubuntu-20.04-dev"     # Custom development image
# or
name = "default"              # System default image

[kernel] Section

Specifies the kernel image for VM boot:

Kernel Selection

name - Kernel image filename
Default - “default.bin” for standard kernel
Custom kernels - For specialized requirements

[kernel]
name = "linux-5.15-custom.bin"   # Custom kernel
# or  
name = "default.bin"             # Standard kernel

[builder] Section

Controls how custom rootfs images are built:

Build System Configuration

name - Build system type
“docker” - Use Docker-based builds
“none” - Skip building, use existing images

[builder]
name = "docker"               # Enable Docker builds
dockerfile = "dev.Dockerfile" # Custom Dockerfile path
# or
name = "none"                 # Disable building

Dockerfile Path

dockerfile - Path to Dockerfile for custom builds
Relative paths - Relative to project directory
Custom paths - Support for complex project structures

[builder]
dockerfile = "docker/development/Dockerfile"  # Custom path
dockerfile = "Dockerfile.prod"                # Production variant

Default Values

System Defaults

When values are omitted, Vers uses these defaults:

[machine]
mem_size_mib = 512
vcpu_count = 1
fs_size_cluster_mib = 1024
fs_size_vm_mib = 512

[rootfs]
name = "default"

[kernel]
name = "default.bin"

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

Loading Behavior

# If vers.toml exists: load values, use defaults for missing sections
# If vers.toml missing: use all defaults (with warning)
vers up
# Warning: vers.toml not found, using default configuration

Configuration Override Hierarchy

Precedence Order (highest to lowest)

Command-line flags - Direct flag values
Environment variables - (if supported)
Configuration file - vers.toml values
System defaults - Built-in fallbacks

Flag Override Examples

# Override memory from command line
vers up --mem-size 4096
# Uses 4096 MiB regardless of vers.toml value

# Override multiple values
vers run --mem-size 2048 --vcpu-count 4 --rootfs custom-image
# All three values overridden

Configuration Validation

Validation Rules

Positive integers - Memory, CPU, and storage values must be > 0
Logical relationships - VM size must not exceed cluster size
Resource constraints - Values must be within system capabilities
Image availability - Referenced images must exist

Common Validation Errors

vers up
# Error: VM filesystem size (4096 MiB) exceeds cluster size (2048 MiB)
# Solution: Increase cluster size or reduce VM size

vers run --mem-size -1
# Error: Invalid memory size (must be positive)
# Solution: Use positive integer for memory allocation

Environment-Specific Configurations

Development Configuration

# vers-dev.toml
[machine]
mem_size_mib = 1024
vcpu_count = 2
fs_size_cluster_mib = 4096
fs_size_vm_mib = 2048

[rootfs]
name = "development-stack"

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

Production Configuration

# vers-prod.toml  
[machine]
mem_size_mib = 4096
vcpu_count = 8
fs_size_cluster_mib = 16384
fs_size_vm_mib = 8192

[rootfs]
name = "production-optimized"

[builder]
name = "none"  # Use pre-built images

Testing Configuration

# vers-test.toml
[machine]
mem_size_mib = 512
vcpu_count = 1
fs_size_cluster_mib = 2048
fs_size_vm_mib = 1024

[rootfs]
name = "test-harness"

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

Configuration Management Patterns

Configuration Templates

# Generate configuration for different environments
function create_config() {
  local env_type=$1
  
  case $env_type in
    "minimal")
      cat > vers.toml <<EOF
[machine]
mem_size_mib = 512
vcpu_count = 1

[rootfs]
name = "minimal"
EOF
      ;;
    "development")
      cat > vers.toml <<EOF
[machine]
mem_size_mib = 2048
vcpu_count = 4

[rootfs]
name = "dev-full"

[builder]
name = "docker"
dockerfile = "Dockerfile.dev"
EOF
      ;;
  esac
}

# Usage
create_config "development"
vers up

Configuration Validation Scripts

#!/bin/bash
# Validate vers.toml before deployment

function validate_config() {
  local config_file="vers.toml"
  
  if [ ! -f "$config_file" ]; then
    echo "Error: $config_file not found"
    return 1
  fi
  
  # Check for required sections
  if ! grep -q "\[machine\]" "$config_file"; then
    echo "Warning: [machine] section missing, will use defaults"
  fi
  
  if ! grep -q "\[rootfs\]" "$config_file"; then
    echo "Warning: [rootfs] section missing, will use defaults"
  fi
  
  # Validate memory size
  local mem_size=$(grep "mem_size_mib" "$config_file" | cut -d'=' -f2 | tr -d ' ')
  if [ -n "$mem_size" ] && [ "$mem_size" -lt 256 ]; then
    echo "Warning: Memory size ${mem_size} MiB may be insufficient"
  fi
  
  echo "Configuration validation completed"
}

# Usage
validate_config

Multi-Environment Configuration Management

# Environment-specific configuration switching
function use_environment() {
  local env=$1
  local config_file="vers-${env}.toml"
  
  if [ -f "$config_file" ]; then
    cp "$config_file" "vers.toml"
    echo "Switched to $env environment configuration"
  else
    echo "Error: Configuration for $env environment not found"
    return 1
  fi
}

# Usage
use_environment "development"  # Copy vers-development.toml to vers.toml
vers up

use_environment "production"   # Switch to production config
vers run

Configuration Best Practices

Resource Planning

# Plan cluster resources for expected branching
[machine]
mem_size_mib = 1024           # Per VM
vcpu_count = 2                # Per VM
fs_size_cluster_mib = 8192    # Total (allows ~8 VMs)
fs_size_vm_mib = 1024         # Per VM

Development vs Production

# Development: Higher resource allocation for tools
[machine]
mem_size_mib = 2048
vcpu_count = 4

# Production: Optimized resource usage
[machine]
mem_size_mib = 1024
vcpu_count = 2

Image Management

# Development: Enable builds for experimentation
[builder]
name = "docker"
dockerfile = "Dockerfile.dev"

# Production: Use stable, pre-built images
[builder]
name = "none"

[rootfs]
name = "production-v1.2.3"

Troubleshooting Configuration Issues

Common Problems

Configuration not loading:

vers up
# Uses defaults instead of vers.toml values
# Cause: TOML syntax errors or file permission issues
# Solution: Validate TOML syntax and file permissions

Resource allocation failures:

vers up
# Error: Insufficient system resources
# Cause: Configuration requests more resources than available
# Solution: Reduce memory/CPU requirements or free system resources

Image not found errors:

vers up --rootfs custom-image
# Error: rootfs image 'custom-image' not found
# Cause: Image name in configuration doesn't exist
# Solution: Verify image name or build required image

Build failures:

vers up
# Error: Dockerfile build failed
# Cause: Invalid Dockerfile path or build context issues
# Solution: Verify dockerfile path and build dependencies

Configuration Debugging

# Test configuration without starting cluster
function debug_config() {
  echo "=== Configuration Debug ==="
  
  if [ -f "vers.toml" ]; then
    echo "Configuration file: vers.toml"
    echo "Contents:"
    cat vers.toml
  else
    echo "No vers.toml found, will use defaults"
  fi
  
  echo ""
  echo "=== Testing with dry-run (if available) ==="
  # Note: Actual dry-run functionality would need CLI support
}

debug_config

Advanced Configuration Patterns

Conditional Configuration

# Generate configuration based on system capabilities
function auto_config() {
  local total_memory=$(free -m | awk '/^Mem:/ {print $2}')
  local cpu_cores=$(nproc)
  
  # Allocate up to 1/4 of system memory
  local vm_memory=$((total_memory / 4))
  # Use up to half of CPU cores
  local vm_cpus=$((cpu_cores / 2))
  
  cat > vers.toml <<EOF
[machine]
mem_size_mib = ${vm_memory}
vcpu_count = ${vm_cpus}
fs_size_cluster_mib = $((vm_memory * 4))
fs_size_vm_mib = ${vm_memory}

[rootfs]
name = "auto-selected"
EOF
  
  echo "Generated configuration based on system: ${vm_memory}MB RAM, ${vm_cpus} CPUs"
}

auto_config

Configuration Inheritance

# Base configuration with overrides
function create_inherited_config() {
  local base_config="vers-base.toml"
  local override_config="vers-override.toml"
  local output_config="vers.toml"
  
  # Start with base configuration
  cp "$base_config" "$output_config"
  
  # Apply overrides (pseudo-code - would need actual TOML merging)
  # merge_toml_files "$output_config" "$override_config"
  
  echo "Created configuration with base + overrides"
}

Dynamic Configuration

# Configuration that adapts to workload
function workload_config() {
  local workload_type=$1
  
  case $workload_type in
    "web-dev")
      cat > vers.toml <<EOF
[machine]
mem_size_mib = 1024
vcpu_count = 2

[rootfs]
name = "node-nginx"
EOF
      ;;
    "data-science")
      cat > vers.toml <<EOF
[machine]
mem_size_mib = 8192
vcpu_count = 8

[rootfs]  
name = "python-ml"
EOF
      ;;
    "mobile-dev")
      cat > vers.toml <<EOF
[machine]
mem_size_mib = 4096
vcpu_count = 4

[rootfs]
name = "android-studio"
EOF
      ;;
  esac
}

# Usage
workload_config "web-dev"
vers up

Configuration Security

Sensitive Information Handling

# Avoid putting sensitive data directly in vers.toml
[machine]
mem_size_mib = 2048

[rootfs]
name = "production"  # Reference by name, not embedded credentials

# Instead, handle secrets in image build process or runtime

Environment-Specific Security

# Development: More permissive for debugging
[builder]
name = "docker"
dockerfile = "Dockerfile.dev"  # May include debug tools

# Production: Minimal, hardened images
[builder]
name = "none"

[rootfs]
name = "hardened-production"   # Security-focused image

Integration with Development Workflows

Git Integration

# Track configuration in version control
git add vers.toml
git commit -m "Add Vers configuration for development environment"

# Environment-specific configurations
git add vers-dev.toml vers-staging.toml vers-prod.toml
git commit -m "Add multi-environment Vers configurations"

CI/CD Integration

# Example CI/CD pipeline (pseudo-YAML)
steps:
  - name: Setup Vers environment
    run: |
      cp vers-ci.toml vers.toml
      vers up
      
  - name: Run tests
    run: |
      vers connect < test-script.sh
      
  - name: Cleanup
    run: |
      vers kill --force --cluster $(vers status | grep Cluster | cut -d' ' -f2)

Team Collaboration

# Shared team configuration
echo "vers.toml" >> .gitignore          # Ignore local overrides
echo "vers-team.toml" > .gitignore      # Don't ignore team template

# Team member setup
cp vers-team.toml vers.toml             # Use team template
# Make local adjustments to vers.toml as needed

Configuration Documentation

Inline Documentation

# Development environment configuration
# Memory: 2GB for comfortable development with dev tools
# CPUs: 4 cores for parallel build processes  
# Storage: 8GB cluster allows multiple feature branches
[machine]
mem_size_mib = 2048     # 2GB RAM
vcpu_count = 4          # 4 CPU cores
fs_size_cluster_mib = 8192  # 8GB total storage
fs_size_vm_mib = 2048   # 2GB per VM

# Use development image with full toolchain
[rootfs]
name = "dev-complete"   # Includes: Node.js, Python, build tools

# Enable Docker builds for custom environments
[builder]
name = "docker"         # Docker-based builds
dockerfile = "Dockerfile.dev"  # Development-specific Dockerfile

Configuration README

# Vers Configuration Guide

## Environment Configurations

- `vers-dev.toml` - Development environment (2GB RAM, 4 CPUs)
- `vers-staging.toml` - Staging environment (4GB RAM, 8 CPUs)  
- `vers-prod.toml` - Production simulation (8GB RAM, 16 CPUs)

## Setup Instructions

1. Copy appropriate template: `cp vers-dev.toml vers.toml`
2. Adjust resources if needed
3. Start environment: `vers up`

## Customization

Modify memory allocation based on your system:
- Minimum: 512 MiB
- Recommended development: 2048 MiB
- Performance testing: 4096+ MiB

Getting Started

​vers config

​Synopsis

​Description

​Configuration File Structure

​Complete vers.toml Example

​Minimal Configuration

​Configuration Sections

​[machine] Section

​Memory Configuration

​CPU Configuration

​Storage Configuration

​[rootfs] Section

​Image Selection

​[kernel] Section

​Kernel Selection

​[builder] Section

​Build System Configuration

​Dockerfile Path

​Default Values

​System Defaults

​Loading Behavior

​Configuration Override Hierarchy

​Precedence Order (highest to lowest)

​Flag Override Examples

​Configuration Validation

​Validation Rules

​Common Validation Errors

​Environment-Specific Configurations

​Development Configuration

​Production Configuration

​Testing Configuration

​Configuration Management Patterns

​Configuration Templates

​Configuration Validation Scripts

​Multi-Environment Configuration Management

​Configuration Best Practices

​Resource Planning

​Development vs Production

​Image Management

​Troubleshooting Configuration Issues

​Common Problems

​Configuration Debugging

​Advanced Configuration Patterns

​Conditional Configuration

​Configuration Inheritance

​Dynamic Configuration

​Configuration Security

​Sensitive Information Handling

​Environment-Specific Security

​Integration with Development Workflows

​Git Integration

​CI/CD Integration

​Team Collaboration

​Configuration Documentation

​Inline Documentation

​Configuration README

​See Also