feat: Support UID/GID when copying files (#1531)

Author: HofmeisterAn

Directory.Packages.props

@@ -5,8 +5,8 @@
     </PropertyGroup>
     <ItemGroup>
         <PackageVersion Include="BouncyCastle.Cryptography" Version="2.6.1"/>
-        <PackageVersion Include="Docker.DotNet.Enhanced.X509" Version="3.128.5"/>
-        <PackageVersion Include="Docker.DotNet.Enhanced" Version="3.128.5"/>
+        <PackageVersion Include="Docker.DotNet.Enhanced.X509" Version="3.129.0"/>
+        <PackageVersion Include="Docker.DotNet.Enhanced" Version="3.129.0"/>
         <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="8.0.0"/>
         <PackageVersion Include="Microsoft.Bcl.HashCode" Version="1.1.1"/>
         <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.3"/>
@@ -64,7 +64,7 @@
         <PackageVersion Include="InfluxDB.Client" Version="4.18.0"/>
         <PackageVersion Include="JanusGraph.Net" Version="1.0.0"/>
         <PackageVersion Include="Keycloak.Net.Core" Version="1.0.20"/>
-        <PackageVersion Include="KubernetesClient" Version="15.0.1"/>
+        <PackageVersion Include="KubernetesClient" Version="17.0.14"/>
         <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.32.1"/>
         <PackageVersion Include="Microsoft.Azure.Kusto.Data" Version="12.2.8"/>
         <PackageVersion Include="Microsoft.Data.SqlClient" Version="5.2.2"/>

docs/api/create_docker_container.md

@@ -58,6 +58,30 @@ _ = new ContainerBuilder()
   .WithResourceMapping(Encoding.Default.GetBytes("{}"), "/app/appsettings.json");
 ```
 
+### Specifying file ownership
+
+When copying files into a container, you can specify the user ID (UID) and group ID (GID) to set the correct ownership of the copied files. This is particularly useful when the container runs as a non-root user or when specific file permissions are required for security or application functionality.
+
+```csharp title="Copying a file with specific UID and GID"
+_ = new ContainerBuilder()
+  .WithResourceMapping(new DirectoryInfo("."), "/app/", uid: 1000, gid: 1000);
+```
+
+### Specifying file permission
+
+When copying files into a container, you can specify the file mode to set the correct permissions for the copied files.
+
+```csharp title="Copying a script with executable permissions"
+_ = new ContainerBuilder()
+  .WithResourceMapping(new DirectoryInfo("."), "/app/", fileMode: Unix.FileMode755);
+```
+
+The `Unix` class provides common permission configurations like `FileMode755` (read, write, execute for owner; read, execute for group and others). For individual permission combinations, you can use the `UnixFileModes` enumeration to create custom configurations.
+
+### Copying files to a running container
+
+The same UID, GID, and file mode arguments are also available when copying files to already running containers using the `IContainer.CopyAsync(...)` APIs.
+
 ## Reading files from the container
 
 The `IContainer` interface offers a `ReadFileAsync(string, CancellationToken)` method to read files from the container. The implementation returns the read bytes. Either process the read bytes in-memory or persist them to the disk.

src/Testcontainers.Cassandra/CassandraContainer.cs

@@ -35,7 +35,7 @@ public async Task<ExecResult> ExecScriptAsync(string scriptContent, Cancellation
     {
         var scriptFilePath = string.Join("/", string.Empty, "tmp", Guid.NewGuid().ToString("D"), Path.GetRandomFileName());
 
-        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, Unix.FileMode644, ct)
+        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, fileMode: Unix.FileMode644, ct: ct)
             .ConfigureAwait(false);
 
         return await ExecAsync(new[] { "cqlsh", "--file", scriptFilePath }, ct)

src/Testcontainers.ClickHouse/ClickHouseContainer.cs

@@ -41,7 +41,7 @@ public async Task<ExecResult> ExecScriptAsync(string scriptContent, Cancellation
     {
         var scriptFilePath = string.Join("/", string.Empty, "tmp", Guid.NewGuid().ToString("D"), Path.GetRandomFileName());
 
-        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, Unix.FileMode644, ct)
+        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, fileMode: Unix.FileMode644, ct: ct)
             .ConfigureAwait(false);
 
         return await ExecAsync(new[] { "clickhouse-client", "--database", _configuration.Database, "--queries-file", scriptFilePath }, ct)

src/Testcontainers.CockroachDb/CockroachDbContainer.cs

@@ -41,7 +41,7 @@ public async Task<ExecResult> ExecScriptAsync(string scriptContent, Cancellation
     {
         var scriptFilePath = string.Join("/", string.Empty, "tmp", Guid.NewGuid().ToString("D"), Path.GetRandomFileName());
 
-        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, Unix.FileMode644, ct)
+        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, fileMode: Unix.FileMode644, ct: ct)
             .ConfigureAwait(false);
 
         return await ExecAsync(new[] { "cockroach", "sql", "--insecure", "--file", scriptFilePath }, ct)

src/Testcontainers.Db2/Db2Container.cs

@@ -39,7 +39,7 @@ public async Task<ExecResult> ExecScriptAsync(string scriptContent, Cancellation
 
         var db2ShellCommand = string.Format(db2ShellCommandFormat, _configuration.Database, _configuration.Username, scriptFilePath);
 
-        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, Unix.FileMode644, ct)
+        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, fileMode: Unix.FileMode644, ct: ct)
             .ConfigureAwait(false);
 
         return await ExecAsync(new[] { "/bin/sh", "-c", db2ShellCommand}, ct)

src/Testcontainers.FakeGcsServer/FakeGcsServerBuilder.cs

@@ -61,7 +61,7 @@ protected override FakeGcsServerBuilder Init()
                 // error: HttpStatusCode.NotFound. The HTTP request appears incorrect. The
                 // container logs indicate the presence of an extra slash: `PUT //upload/storage/v1`.
                 startupScript.Append("-external-url " + new UriBuilder(Uri.UriSchemeHttp, container.Hostname, container.GetMappedPublicPort(FakeGcsServerPort)).ToString().Trim('/'));
-                return container.CopyAsync(Encoding.Default.GetBytes(startupScript.ToString()), StartupScriptFilePath, Unix.FileMode755, ct);
+                return container.CopyAsync(Encoding.Default.GetBytes(startupScript.ToString()), StartupScriptFilePath, fileMode: Unix.FileMode755, ct: ct);
             });
     }
 

src/Testcontainers.FirebirdSql/FirebirdSqlContainer.cs

@@ -41,7 +41,7 @@ public async Task<ExecResult> ExecScriptAsync(string scriptContent, Cancellation
     {
         var scriptFilePath = string.Join("/", string.Empty, "tmp", Guid.NewGuid().ToString("D"), Path.GetRandomFileName());
 
-        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, Unix.FileMode644, ct)
+        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, fileMode: Unix.FileMode644, ct: ct)
             .ConfigureAwait(false);
 
         return await ExecAsync(new[] { "/usr/local/firebird/bin/isql", "-i", scriptFilePath, "-user", _configuration.Username, "-pass", _configuration.Password, _configuration.Database }, ct)

src/Testcontainers.Kafka/KafkaBuilder.cs

@@ -207,7 +207,7 @@ public override KafkaContainer Build()
         var startupKafkaBuilder = kafkaBuilder.WithStartupCallback((container, ct) =>
         {
             var startupScript = vendorConfiguration.CreateStartupScript(kafkaBuilder.DockerResourceConfiguration, container);
-            return container.CopyAsync(Encoding.Default.GetBytes(startupScript), StartupScriptFilePath, Unix.FileMode755, ct);
+            return container.CopyAsync(Encoding.Default.GetBytes(startupScript), StartupScriptFilePath, fileMode: Unix.FileMode755, ct: ct);
         });
 
         return new KafkaContainer(startupKafkaBuilder.DockerResourceConfiguration);

src/Testcontainers.MariaDb/MariaDbContainer.cs

@@ -41,7 +41,7 @@ public async Task<ExecResult> ExecScriptAsync(string scriptContent, Cancellation
     {
         var scriptFilePath = string.Join("/", string.Empty, "tmp", Guid.NewGuid().ToString("D"), Path.GetRandomFileName());
 
-        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, Unix.FileMode644, ct)
+        await CopyAsync(Encoding.Default.GetBytes(scriptContent), scriptFilePath, fileMode: Unix.FileMode644, ct: ct)
             .ConfigureAwait(false);
 
         return await ExecAsync(new[] { "mariadb", _configuration.Database, $"--execute=source {scriptFilePath};" }, ct)
@@ -63,6 +63,6 @@ internal Task WriteConfigurationFileAsync(CancellationToken ct = default)
         config.WriteLine("protocol=TCP");
         config.WriteLine($"user={_configuration.Username}");
         config.WriteLine($"password={_configuration.Password}");
-        return CopyAsync(Encoding.Default.GetBytes(config.ToString()), "/etc/mysql/my.cnf", UnixFileModes.UserRead | UnixFileModes.UserWrite, ct);
+        return CopyAsync(Encoding.Default.GetBytes(config.ToString()), "/etc/mysql/my.cnf", fileMode: UnixFileModes.UserRead | UnixFileModes.UserWrite, ct: ct);
     }
 }