The Docker module provides a comprehensive set of tools for working with Docker containers, images, and compose files in V. It offers high-level abstractions for common Docker operations while maintaining flexibility for advanced use cases.

Core Components

DockerEngine

The main entry point for Docker operations. It manages:

Docker images and containers
Build operations
Registry interactions
Platform-specific settings

// Create a new Docker engine
mut engine := docker.new(
    name: 'myengine'
    localonly: true
)!

DockerContainer

Represents a Docker container with operations for:

Starting/stopping containers
Shell access
Port forwarding
Volume mounting
Container state management

// Create and start a container
mut container := engine.container_create(
    name: 'mycontainer'
    image_repo: 'ubuntu'
    image_tag: 'latest'
)!
container.start()!

DockerImage

Handles Docker image operations:

Image loading/saving
Deletion
Export/import
Image metadata

// Get an image by name
mut image := engine.image_get(
    repo: 'ubuntu'
    tag: 'latest'
)!

DockerCompose

Manages Docker Compose operations:

Service definitions
Multi-container deployments
Network configuration
Volume management

// Create a new compose configuration
mut composer := engine.compose_new(
    name: 'myapp'
)!

// Add a service
mut service := composer.service_new(C
    name: 'web'
    image: 'nginx:latest'
)!

// Configure service
service.port_expose(80, 8080)!
service.env_add('NGINX_HOST', 'localhost')
service.restart_set()

// Start the compose stack
composer.start()!

DockerRegistry

Provides functionality for:

Registry setup and management
Image pushing/pulling
Authentication
SSL configuration

Recipe System

The module includes a powerful recipe system for building Docker images:

DockerBuilderRecipe

Allows declarative definition of Docker images with:

Multi-stage builds
Package installation
File operations
Environment configuration
Service initialization

// Create a new recipe
mut recipe := engine.recipe_new(RecipeArgs{
    name: 'myapp'
    platform: .ubuntu
})!

// Add build steps
recipe.add_package(name: 'nginx,curl')!
recipe.add_copy(source: 'app', dest: '/app')!
recipe.add_env('APP_ENV', 'production')!
recipe.add_expose(ports: ['80/tcp'])!

// Build the image
recipe.build(false)!

Recipe Components

The recipe system supports various Dockerfile instructions through specialized components:

FromItem: Base image specification
RunItem: Command execution
CmdItem: Container entry point
EnvItem: Environment variables
WorkDirItem: Working directory
CopyItem: File copying
ExposeItem: Port exposure
VolumeItem: Volume mounting
ZinitItem: Process management

Examples

Basic Container Management

// Create and manage a container
mut engine := docker.new(DockerEngineArgs{name: 'default'})!
mut container := engine.container_create(
    name: 'webserver'
    image_repo: 'nginx'
    forwarded_ports: ['80:8080/tcp']
)!
container.start()!

Custom Image Build

mut recipe := engine.recipe_new(
    name: 'custom-nginx'
    platform: .ubuntu
)!

recipe.add_package(name: 'nginx')!
recipe.add_file_embedded(
    source: 'nginx.conf'
    dest: '/etc/nginx/nginx.conf'
)!
recipe.add_expose(ports: ['80/tcp'])!

recipe.build(false)!

Multi-Container Setup

mut composer := engine.compose_new(name: 'webapp')!

// Web service
mut web := composer.service_new
    name: 'web'
    image: 'nginx'
)!
web.port_expose(80, 8080)!

// Database service
mut db := composer.service_new(
    name: 'db'
    image: 'postgres'
)!
db.env_add('POSTGRES_PASSWORD', 'secret')

composer.start()!

Error Handling

The module provides specific error types for common scenarios:

ImageGetError: Image retrieval issues
ContainerGetError: Container access problems

Always handle these errors appropriately in your code:

engine.image_get(
    repo: 'nonexistent'
) or {
    if err is ImageGetError {
        if err.notfound {
            // Handle missing image
        }
    }
    return err
}


## Builders 

see https://github.com/threefoldtech/vbuilders/tree/development/builders for examples

How to get started see

https://github.com/threefoldtech/vbuilders/blob/development/docsrc/src/gettingstarted/ubuntu/ubuntu.md