FluentDocker

FluentDocker v3.0 uses a layered, pluggable driver architecture. This design allows for multiple container runtime implementations (like Docker CLI, Docker API, or Podman CLI) to coexist.

The architecture consists of three layers:

1. Fluent API (Builders): The high-level interface used to define deployments. Builders bind to a specific FluentDockerKernel instance.
2. Services (Domain Objects): Objects that represent containers, networks, or volumes, which reference a specific kernel instance.
3. FluentDocker Kernel: The central orchestrator that manages the DriverRegistry, DriverSelector, and DriverRouter. It is instantiable, meaning you can have multiple independent kernels (e.g., one for local Docker and one for remote Docker) running in the same application.
4. Driver Layer: The actual implementation of the container runtime (e.g., dc-1 using Docker CLI, podman-1 using Podman CLI).

In v3.0, all operations are asynchronous. The terminal method for any builder is BuildAsync(), which returns a Task<TResult>.

Key changes from v2:

• Use await .BuildAsync() instead of .Build()
• Use await .StartAsync() instead of .Start()
• Use await .StopAsync() instead of .Stop()
• Use await .RemoveAsync() instead of .Remove()

All async methods accept a CancellationToken to allow for timeouts or manual cancellation.

// Kernel initialization
var kernel = await FluentDockerKernel.Create()
    .WithDockerCli("docker", d => { })
    .BuildAsync();  // TERMINAL ASYNC

// Container deployment
var results = await new Builder()
    .WithinDriver("docker", kernel)
    .UseContainer(c => c.UseImage("nginx"))
    .BuildAsync();  // TERMINAL ASYNC

// Service operations
await results.All[0].StartAsync();
await results.DisposeAllAsync();

// With CancellationToken
using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));
var deployment = await new Builder()
    .WithinDriver("docker", kernel)
    .UseContainer(c => c.UseImage("nginx"))
    .BuildAsync(cts.Token);

v3 allows you to declare networks, containers, and other services in a single builder chain with one terminal Build() call. This ensures all services are managed together. Use results.GetContainer("name") to retrieve specific containers by their assigned name. To ensure network cleanup, use .RemoveOnDispose() on the network configuration.

using var results = new Builder()
    .WithinDriver("docker", kernel)
    .UseNetwork(n => n
        .WithName("backend-net")
        .RemoveOnDispose())
    .UseContainer(c => c
        .UseImage("redis:7-alpine")
        .WithName("cache")
        .WithNetwork("backend-net")
        .ExposePort("6379")
        .WaitForPort("6379/tcp", 30000))
    .UseContainer(c => c
        .UseImage("myapp:latest")
        .WithName("webapp")
        .WithNetwork("backend-net")
        .WithEnvironment("REDIS_HOST", "cache")
        .ExposePort("8080")
        .WaitForPort("8080/tcp", 30000))
    .Build();

var network = results.Networks.First();
var cache = results.GetContainer("cache");
var webapp = results.GetContainer("webapp");

The TemplateString class allows for dynamic path construction using special tokens for system directories, random strings, and environment variables. This is useful for creating unique temporary directories for tests or mounting configuration files.

Supported Variables

Usage Examples

Basic paths and random suffixes:

// Temporary directory
var tempPath = new TemplateString("${TEMP}/myapp");

// With random suffix
var uniquePath = new TemplateString("${TEMP}/test-${RND}");

// Current directory
var workPath = new TemplateString("${PWD}/config");

Environment variables: To access an environment variable, use the ${E_VAR_NAME} syntax. If the variable is unset, the token remains unexpanded as a literal string.

// Access any environment variable with E_ prefix
var homePath = new TemplateString("${E_HOME}/myapp");

// Custom environment variables
Environment.SetEnvironmentVariable("MY_VAR", "custom-value");
var customPath = new TemplateString("${E_MY_VAR}/data");

Combining variables:

var path = new TemplateString("${TEMP}/${E_USER}/session-${RND}");

using FluentDocker.Model.Common;

// Temporary directory
var tempPath = new TemplateString("${TEMP}/myapp");
// Expands to: /tmp/myapp (Linux) or C:\Users\...\AppData\Local\Temp\myapp (Windows)

// With random suffix
var uniquePath = new TemplateString("${TEMP}/test-${RND}");
// Expands to: /tmp/test-tmpk4xz0f.tmp

// Current directory
var workPath = new TemplateString("${PWD}/config");
// Expands to: /current/working/directory/config

FluentDocker uses an extensibility model that allows drivers to expose custom interfaces and builder extensions without modifying the core kernel. This enables driver-specific features (like Podman pods or Docker Swarm modes) to integrate into the fluent API.

The Workflow:

1. Extension Methods (e.g., .UsePod("name")) are called on builders.
2. These methods cast the builder to an IDriverScopedBuilder to access the current Kernel and DriverId.
3. The builder uses TryDriver<T>() or RequireDriver<T>() to resolve the specific driver interface.
4. The kernel resolves the interface via IDriverInterfaceResolver using a cascading strategy:
   • Check the Driver Pack IDriverInterfaceResolver
   • Check the Driver Pack SysCtl
   • Check the Driver IDriverInterfaceResolver
   • Fallback to a direct cast.

┌──────────────────────────────┐
                                 │   Extension Methods          │
                                 │   .UsePod("my-pod")          │
                                 │   .UseSwarmMode(replicas: 3) │
                                 └──────────┬───────────────────┘
                                            │ casts to
                                 ┌──────────▼───────────────────┐
                                 │   IDriverScopedBuilder       │
                                 │   .Kernel + .DriverId        │
                                 └──────────┬───────────────────┘
                                            │ calls
                                 ┌──────────▼───────────────────┐
                                 │   TryDriver<T>() /           │
                                 │   RequireDriver<T>()         │
                                 └──────────┬───────────────────┘
                                            │ delegates to
                        ┌───────────────────▼──────────────────┐
                        │  FluentDockerKernel.SysCtl(id, Type) │
                        └───────────────────┬──────────────────┘
                                            │ resolves via
                        ┌───────────────────▼──────────────────┐
                        │   IDriverInterfaceResolver           │
                        │   on DriverPack or Driver            │
                        └──────────────────────────────────────┘