dockerpool

dockerpool

A Go library for managing a pool of Docker containers with automatic replenishment, graceful shutdown, and concurrent operations control.

Features

• Container pooling — pre-created containers ready for immediate use
• Auto-refill — automatically maintains minimum idle containers
• Graceful shutdown — waits for in-use containers before cleanup
• Concurrent operations limit — prevents Docker daemon overload
• Container sync — recovers existing containers on restart
• Flexible configuration — customize pool size, images, labels, and more

Installation

go get github.com/bermanf/dockerpool

Quick Start

package main

import (
    "context"
    "fmt"
    "github.com/bermanf/dockerpool"
)

func main() {
    ctx := context.Background()

    // Create Docker client
    docker, err := dockerpool.NewDockerClient()
    if err != nil {
        panic(err)
    }
    defer docker.Close()

    // Setup network and pull image
    docker.EnsureNetwork(ctx, "my-network")
    docker.PullImage(ctx, "alpine:latest")
    // Set timeout for container cleanup on errors (default: 30s)
    docker.SetCleanupTimeout(1 * time.Second)

    // Create pool with default config
    pool, err := dockerpool.NewDockerPool(ctx, docker, "my-pool", "my-network", 
        dockerpool.DefaultDockerPoolConfig())
    if err != nil {
        panic(err)
    }
    defer pool.Shutdown(ctx)

    // Acquire container from pool
    container, err := pool.Acquire(ctx)
    if err != nil {
        panic(err)
    }

    // Execute command
    result, _ := container.Exec(ctx, []string{"echo", "Hello!"})
    fmt.Println(result.Stdout)

    // Return container to pool
    pool.Return(ctx, container)
}

Configuration

config := dockerpool.DockerPoolConfig{
    // Pool sizing
    MinIdle: 10,   // Minimum idle containers (default: 5)
    MaxIdle: 100,  // Maximum idle containers (default: 10)

    // Timing
    RefillInterval: 50 * time.Millisecond, // How often to check pool (default: 100ms)

    // Concurrency
    MaxConcurrentDockerOps: 20, // Parallel Docker operations (default: 10)

    // Container settings
    ContainerConfig: dockerpool.CreateContainerOptions{
        Config: &container.Config{
            Image: "python:3.11-alpine",
            Cmd:   []string{"sleep", "infinity"},
        },
    },

    // Custom labels
    Labels: map[string]string{
        "env": "production",
    },

    // Error handling
    OnError: func(err error) {
        log.Printf("Pool error: %v", err)
    },
}

pool, err := dockerpool.NewDockerPool(ctx, docker, "my-pool", "network", config)

Command Execution

Simple execution

result, err := container.Exec(ctx, []string{"ls", "-la"})
// result.Stdout, result.Stderr, result.ExitCode

With options (timeout, limit)

result, err := container.ExecStd(ctx, []string{"cat", "/etc/passwd"}, dockerpool.ExecOptions{
    Timeout: 5 * time.Second,
    Limit:   1024 * 10, // 10KB max output
})

Streaming output

exitCode, err := container.ExecStream(ctx,
    []string{"sh", "-c", "echo building... && sleep 5 && echo done"},
    os.Stdout,  // stdout writer
    os.Stderr,  // stderr writer
    dockerpool.ExecOptions{},
)

With stdin

input := strings.NewReader("hello\nworld\n")
result, err := container.ExecStd(ctx, []string{"grep", "world"}, dockerpool.ExecOptions{
    Stdin: input,
})

Pool Operations

// Acquire container (blocks if pool empty, creates new)
container, err := pool.Acquire(ctx)

// Return to pool (or removes if pool full)
pool.Return(ctx, container)

// Remove without returning to pool
pool.Remove(ctx, container)

// Get metrics
idle := pool.IdleCount()  // Containers in pool
inUse := pool.InUse()     // Containers currently acquired

// Graceful shutdown (waits for in-use containers)
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
err := pool.Shutdown(ctx)

Performance Tips

1. Increase MinIdle for high-throughput scenarios
2. Tune RefillInterval — lower values = faster recovery, more CPU
3. Adjust MaxConcurrentDockerOps based on your Docker daemon capacity
4. Use ExecStream for large outputs to avoid memory pressure

License

MIT