feat: Add Docker build context (#1536)

Author: HofmeisterAn

docs/api/create_docker_image.md

@@ -16,11 +16,19 @@ await futureImage.CreateAsync()
   .ConfigureAwait(false);
 ```
 
+To build a Docker image with Testcontainers, it's important to understand the build context. Testcontainers needs three things:
+
+1. **Docker build context**: The directory containing files Docker can use during the build
+2. **Dockerfile name**: The name of the Dockerfile to use
+3. **Dockerfile directory**: Where the Dockerfile is located
+
 !!!tip
 
-    The Dockerfile must be part of the build context, otherwise the build fails.
+    The build context is optional. If you don't specify one, it defaults to the Dockerfile directory.
+
+Testcontainers creates a tarball with all files and subdirectorys in the build context, incl. the Dockerfile. This tarball is sent to the Docker daemon to build the image. The build context acts as the root for all file operations in the Dockerfile, so all paths (like `COPY` commands) must be relative to it.
 
-It is essential to take into account and comprehend the build context to enable Testcontainers to build the Docker image. Testcontainers generates a tarball that contains all the files and subdirectories within the build context. The tarball is passed to the Docker daemon to build the image. The tarball serves as the new root of the Dockerfile's content. Therefore, all paths must be relative to the new root. If your app or service follows to the following project structure, the build context is `/Users/testcontainers/WeatherForecast/`.
+For example, if your project looks like this, the build context would be: `/Users/testcontainers/WeatherForecast/`.
 
     /
     └── Users/
@@ -61,6 +69,17 @@ RUN dotnet publish $SLN_FILE_PATH --configuration Release --framework net6.0 --o
 ENTRYPOINT ["dotnet", "/app/WeatherForecast.dll"]
 ```
 
+### Choosing a build context
+
+You can use `WithContextDirectory(string)` to set a build context separate from your Dockerfile. This is useful when the Dockerfile is in one directory but the files you want to include are in another.
+
+```csharp
+_ = new ImageFromDockerfileBuilder()
+  .WithContextDirectory("/path/to/build/context")
+  .WithDockerfile("Dockerfile")
+  .WithDockerfileDirectory("/path/to/dockerfile/directory");
+```
+
 ## Delete multi-stage intermediate layers
 
 A multi-stage Docker image build generates intermediate layers that serve as caches. Testcontainers' Resource Reaper is unable to automatically delete these layers after the test execution. The necessary label is not forwarded by the Docker image build. Testcontainers is unable to track the intermediate layers during the test. To delete the intermediate layers after the test execution, pass the Resource Reaper session to each stage.
@@ -92,8 +111,9 @@ _ = new ImageFromDockerfileBuilder()
 | `WithCleanUp`                 | Will remove the image automatically after all tests have been run.           |
 | `WithLabel`                   | Applies metadata to the image e.g. `-l`, `--label "testcontainers=awesome"`. |
 | `WithName`                    | Sets the image name e.g. `-t`, `--tag "testcontainers:0.1.0"`.               |
+| `WithContextDirectory`        | Sets the Docker build context directory.                                     |
 | `WithDockerfile`              | Sets the name of the `Dockerfile`.                                           |
-| `WithDockerfileDirectory`     | Sets the build context (directory path that contains the `Dockerfile`).      |
+| `WithDockerfileDirectory`     | Sets the directory path that contains the `Dockerfile`.                      |
 | `WithImageBuildPolicy`        | Specifies an image build policy to determine when an image is built.         |
 | `WithDeleteIfExists`          | Will remove the image if it already exists.                                  |
 | `WithBuildArgument`           | Sets build-time variables e.g `--build-arg "MAGIC_NUMBER=42"`.               |

src/Testcontainers/Builders/IImageFromDockerfileBuilder`1.cs

@@ -29,26 +29,35 @@ public interface IImageFromDockerfileBuilder<out TBuilderEntity>
     TBuilderEntity WithName(IImage image);
 
     /// <summary>
-    /// Sets the Dockerfile.
+    /// Sets the directory to use as the Docker build context.
+    /// This is the directory that Docker will use to resolve files referenced in the Dockerfile.
     /// </summary>
-    /// <param name="dockerfile">An absolute path or a name value within the Docker build context.</param>
+    /// <param name="contextDirectory">An absolute path or relative name of the directory to use as the Docker build context.</param>
+    /// <returns>A configured instance of <typeparamref name="TBuilderEntity" />.</returns>
+    [PublicAPI]
+    TBuilderEntity WithContextDirectory(string contextDirectory);
+
+    /// <summary>
+    /// Sets the path to the Dockerfile to use for the build.
+    /// </summary>
+    /// <param name="dockerfile">The filename or path of the Dockerfile.</param>
     /// <returns>A configured instance of <typeparamref name="TBuilderEntity" />.</returns>
     [PublicAPI]
     TBuilderEntity WithDockerfile(string dockerfile);
 
     /// <summary>
-    /// Sets the Dockerfile directory.
+    /// Sets the directory containing the Dockerfile.
     /// </summary>
-    /// <param name="dockerfileDirectory">An absolute path or a name value to the Docker build context.</param>
+    /// <param name="dockerfileDirectory">An absolute path or relative path to the directory containing the Dockerfile.</param>
     /// <returns>A configured instance of <typeparamref name="TBuilderEntity" />.</returns>
     [PublicAPI]
     TBuilderEntity WithDockerfileDirectory(string dockerfileDirectory);
 
     /// <summary>
-    /// Sets the Dockerfile directory.
+    /// Sets the directory containing the Dockerfile.
     /// </summary>
     /// <param name="commonDirectoryPath">A common directory path that contains the Dockerfile directory.</param>
-    /// <param name="dockerfileDirectory">A relative path or a name value to the Docker build context.</param>
+    /// <param name="dockerfileDirectory">An absolute path or relative path to the directory containing the Dockerfile.</param>
     /// <returns>A configured instance of <typeparamref name="TBuilderEntity" />.</returns>
     [PublicAPI]
     TBuilderEntity WithDockerfileDirectory(CommonDirectoryPath commonDirectoryPath, string dockerfileDirectory);

src/Testcontainers/Builders/ImageFromDockerfileBuilder.cs

@@ -63,6 +63,12 @@ public ImageFromDockerfileBuilder WithName(IImage image)
       return Merge(DockerResourceConfiguration, new ImageFromDockerfileConfiguration(image: image.ApplyHubImageNamePrefix()));
     }
 
+    /// <inheritdoc />
+    public ImageFromDockerfileBuilder WithContextDirectory(string contextDirectory)
+    {
+      return Merge(DockerResourceConfiguration, new ImageFromDockerfileConfiguration(contextDirectory: contextDirectory));
+    }
+
     /// <inheritdoc />
     public ImageFromDockerfileBuilder WithDockerfile(string dockerfile)
     {

src/Testcontainers/Clients/TestcontainersClient.cs

@@ -372,6 +372,7 @@ public async Task<string> BuildAsync(IImageFromDockerfileConfiguration configura
       if (configuration.ImageBuildPolicy(cachedImage))
       {
         var dockerfileArchive = new DockerfileArchive(
+          configuration.ContextDirectory,
           configuration.DockerfileDirectory,
           configuration.Dockerfile,
           configuration.Image,

src/Testcontainers/Configurations/Images/IImageFromDockerfileConfiguration.cs

@@ -17,6 +17,11 @@ public interface IImageFromDockerfileConfiguration : IResourceConfiguration<Imag
     /// </summary>
     bool? DeleteIfExists { get; }
 
+    /// <summary>
+    /// Gets the context directory.
+    /// </summary>
+    string ContextDirectory { get; }
+
     /// <summary>
     /// Gets the Dockerfile.
     /// </summary>

src/Testcontainers/Configurations/Images/ImageFromDockerfileConfiguration.cs

@@ -15,6 +15,7 @@ internal sealed class ImageFromDockerfileConfiguration : ResourceConfiguration<I
     /// <summary>
     /// Initializes a new instance of the <see cref="ImageFromDockerfileConfiguration" /> class.
     /// </summary>
+    /// <param name="contextDirectory">The context directory.</param>
     /// <param name="dockerfile">The Dockerfile.</param>
     /// <param name="dockerfileDirectory">The Dockerfile directory.</param>
     /// <param name="target">The target.</param>
@@ -23,6 +24,7 @@ internal sealed class ImageFromDockerfileConfiguration : ResourceConfiguration<I
     /// <param name="buildArguments">A list of build arguments.</param>
     /// <param name="deleteIfExists">A value indicating whether Testcontainers removes an existing image or not.</param>
     public ImageFromDockerfileConfiguration(
+      string contextDirectory = null,
       string dockerfile = null,
       string dockerfileDirectory = null,
       string target = null,
@@ -31,6 +33,7 @@ public ImageFromDockerfileConfiguration(
       IReadOnlyDictionary<string, string> buildArguments = null,
       bool? deleteIfExists = null)
     {
+      ContextDirectory = contextDirectory;
       Dockerfile = dockerfile;
       DockerfileDirectory = dockerfileDirectory;
       Target = target;
@@ -66,6 +69,7 @@ public ImageFromDockerfileConfiguration(IImageFromDockerfileConfiguration resour
     public ImageFromDockerfileConfiguration(IImageFromDockerfileConfiguration oldValue, IImageFromDockerfileConfiguration newValue)
       : base(oldValue, newValue)
     {
+      ContextDirectory = BuildConfiguration.Combine(oldValue.ContextDirectory, newValue.ContextDirectory);
       Dockerfile = BuildConfiguration.Combine(oldValue.Dockerfile, newValue.Dockerfile);
       DockerfileDirectory = BuildConfiguration.Combine(oldValue.DockerfileDirectory, newValue.DockerfileDirectory);
       Target = BuildConfiguration.Combine(oldValue.Target, newValue.Target);
@@ -79,6 +83,10 @@ public ImageFromDockerfileConfiguration(IImageFromDockerfileConfiguration oldVal
     [JsonIgnore]
     public bool? DeleteIfExists { get; }
 
+    /// <inheritdoc />
+    [JsonIgnore]
+    public string ContextDirectory { get; }
+
     /// <inheritdoc />
     [JsonIgnore]
     public string Dockerfile { get; }