|
| 1 | +--- |
| 2 | +description: Integrate Docker Compose directly into your applications with the Compose SDK. |
| 3 | +keywords: docker compose sdk, compose api, Docker developer SDK |
| 4 | +title: Using the Compose SDK |
| 5 | +linkTitle: Compose SDK |
| 6 | +weight: 60 |
| 7 | +params: |
| 8 | + sidebar: |
| 9 | + badge: |
| 10 | + color: green |
| 11 | + text: New |
| 12 | +--- |
| 13 | + |
| 14 | +{{< summary-bar feature_name="Compose SDK" >}} |
| 15 | + |
| 16 | +The `docker/compose` package can be used as a Go library by third-party applications to programmatically manage |
| 17 | +containerized applications defined in Compose files. This SDK provides a comprehensive API that lets you |
| 18 | +integrate Compose functionality directly into your applications, allowing you to load, validate, and manage |
| 19 | +multi-container environments without relying on the Compose CLI. |
| 20 | + |
| 21 | +Whether you need to orchestrate containers as part of |
| 22 | +a deployment pipeline, build custom management tools, or embed container orchestration into your application, the |
| 23 | +Compose SDK offers the same powerful capabilities that drive the Docker Compose command-line tool. |
| 24 | + |
| 25 | +## Set up the SDK |
| 26 | + |
| 27 | +To get started, create an SDK instance using the `NewComposeService()` function, which initializes a service with the |
| 28 | +necessary configuration to interact with the Docker daemon and manage Compose projects. This service instance provides |
| 29 | +methods for all core Compose operations including creating, starting, stopping, and removing containers, as well as |
| 30 | +loading and validating Compose files. The service handles the underlying Docker API interactions and resource |
| 31 | +management, allowing you to focus on your application logic. |
| 32 | + |
| 33 | +### Requirements |
| 34 | + |
| 35 | +Before using the SDK, make sure you're using a compatible version of the Docker CLI. |
| 36 | + |
| 37 | +```go |
| 38 | +require ( |
| 39 | + github.com/docker/cli v28.5.2+incompatible |
| 40 | +) |
| 41 | +``` |
| 42 | + |
| 43 | +Docker CLI version 29.0.0 and later depends on the new `github.com/moby/moby` module, whereas Docker Compose v5 currently depends on `github.com/docker/docker`. This means you need to pin `docker/cli v28.5.2+incompatible` to ensure compatibility and avoid build errors. |
| 44 | + |
| 45 | +### Example usage |
| 46 | + |
| 47 | +Here's a basic example demonstrating how to load a Compose project and start the services: |
| 48 | + |
| 49 | +```go |
| 50 | +package main |
| 51 | + |
| 52 | +import ( |
| 53 | + "context" |
| 54 | + "log" |
| 55 | + |
| 56 | + "github.com/docker/cli/cli/command" |
| 57 | + "github.com/docker/cli/cli/flags" |
| 58 | + "github.com/docker/compose/v5/pkg/api" |
| 59 | + "github.com/docker/compose/v5/pkg/compose" |
| 60 | +) |
| 61 | + |
| 62 | +func main() { |
| 63 | + ctx := context.Background() |
| 64 | + |
| 65 | + dockerCLI, err := command.NewDockerCli() |
| 66 | + if err != nil { |
| 67 | + log.Fatalf("Failed to create docker CLI: %v", err) |
| 68 | + } |
| 69 | + err = dockerCLI.Initialize(&flags.ClientOptions{}) |
| 70 | + if err != nil { |
| 71 | + log.Fatalf("Failed to initialize docker CLI: %v", err) |
| 72 | + } |
| 73 | + |
| 74 | + // Create a new Compose service instance |
| 75 | + service, err := compose.NewComposeService(dockerCLI) |
| 76 | + if err != nil { |
| 77 | + log.Fatalf("Failed to create compose service: %v", err) |
| 78 | + } |
| 79 | + |
| 80 | + // Load the Compose project from a compose file |
| 81 | + project, err := service.LoadProject(ctx, api.ProjectLoadOptions{ |
| 82 | + ConfigPaths: []string{"compose.yaml"}, |
| 83 | + ProjectName: "my-app", |
| 84 | + }) |
| 85 | + if err != nil { |
| 86 | + log.Fatalf("Failed to load project: %v", err) |
| 87 | + } |
| 88 | + |
| 89 | + // Start the services defined in the Compose file |
| 90 | + err = service.Up(ctx, project, api.UpOptions{ |
| 91 | + Create: api.CreateOptions{}, |
| 92 | + Start: api.StartOptions{}, |
| 93 | + }) |
| 94 | + if err != nil { |
| 95 | + log.Fatalf("Failed to start services: %v", err) |
| 96 | + } |
| 97 | + |
| 98 | + log.Printf("Successfully started project: %s", project.Name) |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +This example demonstrates the core workflow - creating a service instance, loading a project from a Compose file, and |
| 103 | +starting the services. The SDK provides many additional operations for managing the lifecycle of your containerized |
| 104 | +application. |
| 105 | + |
| 106 | +## Customizing the SDK |
| 107 | + |
| 108 | +The `NewComposeService()` function accepts optional `compose.Option` parameters to customize the SDK behavior. These |
| 109 | +options allow you to configure I/O streams, concurrency limits, dry-run mode, and other advanced features. |
| 110 | + |
| 111 | +```go |
| 112 | + // Create a custom output buffer to capture logs |
| 113 | + var outputBuffer bytes.Buffer |
| 114 | + |
| 115 | + // Create a compose service with custom options |
| 116 | + service, err := compose.NewComposeService(dockerCLI, |
| 117 | + compose.WithOutputStream(&outputBuffer), // Redirect output to custom writer |
| 118 | + compose.WithErrorStream(os.Stderr), // Use stderr for errors |
| 119 | + compose.WithMaxConcurrency(4), // Limit concurrent operations |
| 120 | + compose.WithPrompt(compose.AlwaysOkPrompt()), // Auto-confirm all prompts |
| 121 | + ) |
| 122 | +``` |
| 123 | + |
| 124 | +### Available options |
| 125 | + |
| 126 | +- `WithOutputStream(io.Writer)`: Redirect standard output to a custom writer |
| 127 | +- `WithErrorStream(io.Writer)`: Redirect error output to a custom writer |
| 128 | +- `WithInputStream(io.Reader)`: Provide a custom input stream for interactive prompts |
| 129 | +- `WithStreams(out, err, in)`: Set all I/O streams at once |
| 130 | +- `WithMaxConcurrency(int)`: Limit the number of concurrent operations against the Docker API |
| 131 | +- `WithPrompt(Prompt)`: Customize user confirmation behavior (use `AlwaysOkPrompt()` for non-interactive mode) |
| 132 | +- `WithDryRun`: Run operations in dry-run mode without actually applying changes |
| 133 | +- `WithContextInfo(api.ContextInfo)`: Set custom Docker context information |
| 134 | +- `WithProxyConfig(map[string]string)`: Configure HTTP proxy settings for builds |
| 135 | +- `WithEventProcessor(progress.EventProcessor)`: Receive progress events and operation notifications |
| 136 | + |
| 137 | +These options provide fine-grained control over the SDK's behavior, making it suitable for various integration |
| 138 | +scenarios including CLI tools, web services, automation scripts, and testing environments. |
| 139 | + |
| 140 | +## Tracking operations with `EventProcessor` |
| 141 | + |
| 142 | +The `EventProcessor` interface allows you to monitor Compose operations in real-time by receiving events about changes |
| 143 | +applied to Docker resources such as images, containers, volumes, and networks. This is particularly useful for building |
| 144 | +user interfaces, logging systems, or monitoring tools that need to track the progress of Compose operations. |
| 145 | + |
| 146 | +### Understanding `EventProcessor` |
| 147 | + |
| 148 | +A Compose operation, such as `up`, `down`, `build`, performs a series of changes to Docker resources. The |
| 149 | +`EventProcessor` receives notifications about these changes through three key methods: |
| 150 | + |
| 151 | +- `Start(ctx, operation)`: Called when a Compose operation begins, for example `up` |
| 152 | +- `On(events...)`: Called with progress events for individual resource changes, for example, container starting, image |
| 153 | + being pulled |
| 154 | +- `Done(operation, success)`: Called when the operation completes, indicating success or failure |
| 155 | + |
| 156 | +Each event contains information about the resource being modified, its current status, and progress indicators when |
| 157 | +applicable (such as download progress for image pulls). |
| 158 | + |
| 159 | +### Event status types |
| 160 | + |
| 161 | +Events report resource changes with the following status types: |
| 162 | + |
| 163 | +- Working: Operation is in progress, for example, creating, starting, pulling |
| 164 | +- Done: Operation completed successfully |
| 165 | +- Warning: Operation completed with warnings |
| 166 | +- Error: Operation failed |
| 167 | + |
| 168 | +Common status text values include: `Creating`, `Created`, `Starting`, `Started`, `Running`, `Stopping`, `Stopped`, |
| 169 | +`Removing`, `Removed`, `Building`, `Built`, `Pulling`, `Pulled`, and more. |
| 170 | + |
| 171 | +### Built-in `EventProcessor` implementations |
| 172 | + |
| 173 | +The SDK provides three ready-to-use `EventProcessor` implementations: |
| 174 | + |
| 175 | +- `progress.NewTTYWriter(io.Writer)`: Renders an interactive terminal UI with progress bars and task lists |
| 176 | + (similar to the Docker Compose CLI output) |
| 177 | +- `progress.NewPlainWriter(io.Writer)`: Outputs simple text-based progress messages suitable for non-interactive |
| 178 | + environments or log files |
| 179 | +- `progress.NewJSONWriter()`: Render events as JSON objects |
| 180 | +- `progress.NewQuietWriter()`: (Default) Silently processes events without producing any output |
| 181 | + |
| 182 | +Using `EventProcessor`, a custom UI can be plugged into `docker/compose`. |
0 commit comments