How do I use FluentDocker with Podman instead of Docker?

Set the container engine explicitly with ContainerEngine.Podman.SetContainerEngine(). The API works identically, and FluentDocker auto-detects binary name differences, making it a drop-in replacement for Docker in .NET code.

FluentDocker vs Docker.DotNet – which should I use?

FluentDocker offers a higher-level fluent API ideal for integration testing and management, while Docker.DotNet is a lower-level client. Choose FluentDocker for ease of use in .NET apps with built-in utilities, and Docker.DotNet for more granular control over Docker API calls.

How to wait for a container to be ready in FluentDocker?

Use methods like WaitForPort or WaitForProcess in the fluent API. For example, .WaitForPort("5432/tcp", 30000) waits for a PostgreSQL container's port to open within 30 seconds, ensuring readiness before proceeding.

Can FluentDocker run docker-compose files programmatically?

Yes, it supports docker-compose via the UseCompose() method. You can load compose files, manage services, and wait for conditions like HTTP responses, as shown in the WordPress compose example in the README.

Is sudo required for FluentDocker on Linux?

By default, it expects no sudo, but you can configure it with SudoMechanism for password or no-password sudo. Podman often doesn't require sudo due to rootless design, but Docker might need setup adjustments.

How to copy files to a container using FluentDocker?

Use methods like CopyTo or CopyOnStart. For instance, .CopyTo("/bin", hostPath) copies files from the host to the container after it's started, and the README provides examples with file system operations.

Open-Awesome

FluentDocker

Apache-2.0C#2.80.0

A .NET library for interacting with Docker and Docker Compose via a fluent API, supporting local and remote containers in tests and applications.

GitHub

1.4k stars104 forks0 contributors

What is FluentDocker?

FluentDocker is a .NET library that provides a fluent, type-safe API for interacting with Docker and Docker Compose. It allows developers to programmatically manage containers—such as starting, stopping, and configuring them—directly within .NET applications and unit tests. The library solves the problem of integrating Docker operations into .NET codebases without relying on shell commands or external scripts.

Target Audience

.NET developers who need to integrate Docker containers into their applications, especially for integration testing, local development environments, or CI/CD pipelines. It's also useful for DevOps engineers building .NET-based tooling around container management.

Value Proposition

Developers choose FluentDocker for its intuitive fluent API that reduces boilerplate, its first-class support for both Docker and Podman, and its seamless integration with .NET test frameworks. Unlike raw command-line calls, it provides type safety, better error handling, and built-in utilities like port waiting and file operations.

Overview

Use docker, docker-compose local and remote in tests and your .NET core/full framework apps via a FluentAPI

Use Cases

Best For

Integration testing with ephemeral databases (e.g., PostgreSQL, MySQL) in .NET
Spinning up multi-container environments (e.g., WordPress with MySQL) for local development
Building .NET tools that automate Docker container lifecycle management
Running Docker Compose projects programmatically from .NET applications
Creating self-hosted .NET services that rely on containerized dependencies
Testing microservices with dependent containers in .NET test suites

Not Ideal For

Non-.NET projects or polyglot teams needing container management across multiple programming languages
Scenarios where performance is critical and the abstraction layer of a fluent API introduces unacceptable latency
Simple ad-hoc Docker tasks better handled by shell scripts or direct CLI commands

Pros & Cons

Pros

Fluent API Design

Provides chainable methods for building and managing containers, as shown in examples like configuring a PostgreSQL container with environment variables and port waiting in a single fluent chain.

Multi-Engine Support

Supports both Docker and Podman with auto-detection, allowing flexibility in container engine choice, detailed in the Container Engine Configuration section with explicit engine setting options.

Test Integration

Includes base classes for MSTest and xUnit, simplifying container-based testing in .NET, evidenced by separate NuGet packages for test framework support.

Built-in Utilities

Features like port waiting, file copying, and networking support reduce manual setup, demonstrated in code snippets for waiting on ports and mounting volumes.

Cons

Breaking Changes

The README mentions breaking changes, such as autodetecting compose version, which can disrupt existing implementations without prior warning, requiring code updates.

Complex Remote Setup

Connecting to remote Docker daemons requires SSH configuration and certificate management, adding setup overhead as described in the remote daemon section with manual steps for SSH tunnels.

.NET Lock-in

Limited to .NET ecosystems, making it unsuitable for projects using other languages or requiring cross-platform tooling beyond .NET, as it relies on .NET frameworks and standards.

Frequently Asked Questions

Related Projects

AutoMapper

A convention-based object-object mapper in .NET.

Stars10,187

Forks2,415

Last commit12 days ago

Humanizer

Humanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities

Stars9,605

Forks1,047

Last commit14 days ago

AngleSharp

:angel: The ultimate angle brackets parser library parsing HTML5, MathML, SVG and CSS to construct a DOM based on the official W3C specifications.

Stars5,493

Forks590

Last commit15 days ago

markdig

A fast, powerful, CommonMark compliant, extensible Markdown processor for .NET

Stars5,210

Forks507