sal/virt/README.md

SAL Virt Package

The sal-virt package provides comprehensive virtualization and containerization tools for building, managing, and deploying containers and filesystem layers.

Features

• Buildah: OCI/Docker image building with builder pattern API
• Nerdctl: Container lifecycle management with containerd
• RFS: Remote filesystem mounting and layer management
• Cross-Platform: Works across Windows, macOS, and Linux
• Rhai Integration: Full support for Rhai scripting language
• Error Handling: Comprehensive error types and handling

Modules

Buildah

Container image building with Buildah, providing:

• Builder pattern for container configuration
• Image management and operations
• Content operations (copy, add, run commands)
• Debug mode support

Nerdctl

Container management with Nerdctl, providing:

• Container lifecycle management (create, start, stop, remove)
• Image operations (pull, push, build, tag)
• Network and volume management
• Health checks and resource limits
• Builder pattern for container configuration

RFS

Remote filesystem operations, providing:

• Mount/unmount operations for various filesystem types
• Pack/unpack operations for filesystem layers
• Support for Local, SSH, S3, WebDAV, and custom filesystems
• Store specifications for different backends

Usage

Basic Buildah Example

use sal_virt::buildah::Builder;

// Create a new builder
let mut builder = Builder::new("my-container", "alpine:latest")?;

// Configure the builder
builder.set_debug(true);

// Add content and run commands
builder.copy("./app", "/usr/local/bin/app")?;
builder.run(&["chmod", "+x", "/usr/local/bin/app"])?;

// Commit the image
let image_id = builder.commit("my-app:latest")?;

Basic Nerdctl Example

use sal_virt::nerdctl::Container;

// Create a container from an image
let container = Container::from_image("web-app", "nginx:alpine")?
    .with_port("8080:80")
    .with_volume("/host/data:/app/data")
    .with_env("ENV_VAR", "production")
    .with_restart_policy("always");

// Run the container
let result = container.run()?;

Basic RFS Example

use sal_virt::rfs::{RfsBuilder, MountType, StoreSpec};

// Mount a remote filesystem
let mount = RfsBuilder::new("user@host:/remote/path", "/local/mount", MountType::SSH)
    .with_option("read_only", "true")
    .mount()?;

// Pack a directory
let specs = vec![StoreSpec::new("file").with_option("path", "/tmp/store")];
let pack_result = pack_directory("/source/dir", "/output/pack.rfs", &specs)?;

Rhai Integration

All functionality is available in Rhai scripts:

// Buildah in Rhai
let builder = bah_new("my-container", "alpine:latest");
builder.copy("./app", "/usr/local/bin/app");
builder.run(["chmod", "+x", "/usr/local/bin/app"]);

// Nerdctl in Rhai
let container = nerdctl_container_from_image("web-app", "nginx:alpine")
    .with_port("8080:80")
    .with_env("ENV", "production");
container.run();

// RFS in Rhai
let mount_options = #{ "read_only": "true" };
rfs_mount("user@host:/remote", "/local/mount", "ssh", mount_options);

Dependencies

• sal-process: For command execution
• sal-os: For filesystem operations
• anyhow: For error handling
• serde: For serialization
• rhai: For scripting integration

Testing

The package includes comprehensive tests:

# Run all tests
cargo test

# Run specific test suites
cargo test buildah_tests
cargo test nerdctl_tests
cargo test rfs_tests

# Run Rhai integration tests
cargo test --test rhai_integration

Error Handling

Each module provides its own error types:

• BuildahError: For Buildah operations
• NerdctlError: For Nerdctl operations
• RfsError: For RFS operations

All errors implement std::error::Error and provide detailed error messages.

Platform Support

• Linux: Full support for all features
• macOS: Full support (requires Docker Desktop or similar)
• Windows: Full support (requires Docker Desktop or WSL2)

Security

• Credentials are handled securely and never logged
• URLs with passwords are masked in logs
• All operations respect filesystem permissions
• Network operations use secure defaults

Configuration

Most operations can be configured through environment variables:

• BUILDAH_DEBUG: Enable debug mode for Buildah
• NERDCTL_DEBUG: Enable debug mode for Nerdctl
• RFS_DEBUG: Enable debug mode for RFS

License

Apache-2.0