feat: Support UID/GID when copying files

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);
     }
 }

src/Testcontainers.MongoDb/MongoDbBuilder.cs

@@ -79,7 +79,7 @@ public MongoDbBuilder WithReplicaSet(string replicaSetName = "rs0")
 
         return Merge(DockerResourceConfiguration, new MongoDbConfiguration(replicaSetName: replicaSetName))
             .WithCommand("--replSet", replicaSetName, "--keyFile", KeyFileFilePath, "--bind_ip_all")
-            .WithResourceMapping(Encoding.Default.GetBytes(initKeyFileScript.ToString()), InitKeyFileScriptFilePath, Unix.FileMode755);
+            .WithResourceMapping(Encoding.Default.GetBytes(initKeyFileScript.ToString()), InitKeyFileScriptFilePath, fileMode: Unix.FileMode755);
     }
 
     /// <inheritdoc />

src/Testcontainers.MongoDb/MongoDbContainer.cs

@@ -40,7 +40,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);
 
         var whichMongoDbShell = await ExecAsync(new[] { "which", "mongosh" }, ct)

src/Testcontainers.MsSql/MsSqlContainer.cs

@@ -62,7 +62,7 @@ public async Task<ExecResult> ExecScriptAsync(string scriptContent, Cancellation
         var sqlCmdFilePath = await GetSqlCmdFilePathAsync(ct)
             .ConfigureAwait(false);
 
-        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[] { sqlCmdFilePath, "-C", "-b", "-r", "1", "-U", _configuration.Username, "-P", _configuration.Password, "-i", scriptFilePath }, ct)

src/Testcontainers.MySql/MySqlContainer.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[] { "mysql", _configuration.Database, $"--execute=source {scriptFilePath};" }, ct)
@@ -77,6 +77,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);
     }
 }

src/Testcontainers.Oracle/OracleContainer.cs

@@ -36,7 +36,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[] { "/bin/sh", "-c", $"exit | sqlplus -LOGON -SILENT {_configuration.Username}/{_configuration.Password}@localhost:1521/{_configuration.Database} @{scriptFilePath}" }, ct)

src/Testcontainers.PostgreSql/PostgreSqlContainer.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[] { "psql", "--username", _configuration.Username, "--dbname", _configuration.Database, "--file", scriptFilePath }, ct)

src/Testcontainers.Pulsar/PulsarContainer.cs

@@ -116,7 +116,7 @@ internal Task CopyStartupScriptAsync(CancellationToken ct = default)
             startupScript.Write(" --no-stream-storage");
         }
 
-        return CopyAsync(Encoding.Default.GetBytes(startupScript.ToString()), PulsarBuilder.StartupScriptFilePath, Unix.FileMode755, ct);
+        return CopyAsync(Encoding.Default.GetBytes(startupScript.ToString()), PulsarBuilder.StartupScriptFilePath, fileMode: Unix.FileMode755, ct: ct);
     }
 
     private static bool IsVersionAffectedByGhIssue22811(System.Version version)

src/Testcontainers.Qdrant/QdrantBuilder.cs

@@ -59,8 +59,8 @@ public QdrantBuilder WithCertificate(string certificate, string certificateKey)
             .WithEnvironment("QDRANT__SERVICE__ENABLE_TLS", "1")
             .WithEnvironment("QDRANT__TLS__CERT", CertificateFilePath)
             .WithEnvironment("QDRANT__TLS__KEY", CertificateKeyFilePath)
-            .WithResourceMapping(Encoding.UTF8.GetBytes(certificate), CertificateFilePath)
-            .WithResourceMapping(Encoding.UTF8.GetBytes(certificateKey), CertificateKeyFilePath);
+            .WithResourceMapping(Encoding.Default.GetBytes(certificate), CertificateFilePath)
+            .WithResourceMapping(Encoding.Default.GetBytes(certificateKey), CertificateKeyFilePath);
     }
 
     /// <inheritdoc />

src/Testcontainers.Redis/RedisContainer.cs

@@ -32,7 +32,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[] { "redis-cli", "--eval", scriptFilePath, "0" }, ct)

src/Testcontainers.Redpanda/RedpandaBuilder.cs

@@ -63,7 +63,7 @@ protected override RedpandaBuilder Init()
                 startupScript.Append("--memory 1G ");
                 startupScript.Append("--kafka-addr PLAINTEXT://0.0.0.0:29092,OUTSIDE://0.0.0.0:9092 ");
                 startupScript.Append("--advertise-kafka-addr PLAINTEXT://127.0.0.1:29092,OUTSIDE://" + container.Hostname + ":" + container.GetMappedPublicPort(RedpandaPort));
-                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/Builders/ContainerBuilder`3.cs

@@ -208,66 +208,66 @@ public TBuilderEntity WithResourceMapping(IResourceMapping resourceMapping)
     }
 
     /// <inheritdoc />
-    public TBuilderEntity WithResourceMapping(byte[] resourceContent, string filePath, UnixFileModes fileMode = Unix.FileMode644)
+    public TBuilderEntity WithResourceMapping(byte[] resourceContent, string filePath, uint uid = 0, uint gid = 0, UnixFileModes fileMode = Unix.FileMode644)
     {
-      return WithResourceMapping(new BinaryResourceMapping(resourceContent, filePath, fileMode));
+      return WithResourceMapping(new BinaryResourceMapping(resourceContent, filePath, uid, gid, fileMode));
     }
 
     /// <inheritdoc />
-    public TBuilderEntity WithResourceMapping(string source, string target, UnixFileModes fileMode = Unix.FileMode644)
+    public TBuilderEntity WithResourceMapping(string source, string target, uint uid = 0, uint gid = 0, UnixFileModes fileMode = Unix.FileMode644)
     {
       if (Uri.IsWellFormedUriString(source, UriKind.Absolute) && Uri.TryCreate(source, UriKind.Absolute, out var uri) && new[] { Uri.UriSchemeHttp, Uri.UriSchemeHttps, Uri.UriSchemeFile }.Contains(uri.Scheme))
       {
-        return WithResourceMapping(uri, target, fileMode);
+        return WithResourceMapping(uri, target, uid, gid, fileMode);
       }
 
       var fileAttributes = File.GetAttributes(source);
 
       if ((fileAttributes & FileAttributes.Directory) == FileAttributes.Directory)
       {
-        return WithResourceMapping(new DirectoryInfo(source), target, fileMode);
+        return WithResourceMapping(new DirectoryInfo(source), target, uid, gid, fileMode);
       }
       else
       {
-        return WithResourceMapping(new FileInfo(source), target, fileMode);
+        return WithResourceMapping(new FileInfo(source), target, uid, gid, fileMode);
       }
     }
 
     /// <inheritdoc />
-    public TBuilderEntity WithResourceMapping(DirectoryInfo source, string target, UnixFileModes fileMode = Unix.FileMode644)
+    public TBuilderEntity WithResourceMapping(DirectoryInfo source, string target, uint uid = 0, uint gid = 0, UnixFileModes fileMode = Unix.FileMode644)
     {
-      return WithResourceMapping(new FileResourceMapping(source.FullName, target, fileMode));
+      return WithResourceMapping(new FileResourceMapping(source.FullName, target, uid, gid, fileMode));
     }
 
     /// <inheritdoc />
-    public TBuilderEntity WithResourceMapping(FileInfo source, string target, UnixFileModes fileMode = Unix.FileMode644)
+    public TBuilderEntity WithResourceMapping(FileInfo source, string target, uint uid = 0, uint gid = 0, UnixFileModes fileMode = Unix.FileMode644)
     {
-      return WithResourceMapping(new FileResourceMapping(source.FullName, target, fileMode));
+      return WithResourceMapping(new FileResourceMapping(source.FullName, target, uid, gid, fileMode));
     }
 
     /// <inheritdoc />
-    public TBuilderEntity WithResourceMapping(FileInfo source, FileInfo target, UnixFileModes fileMode = Unix.FileMode644)
+    public TBuilderEntity WithResourceMapping(FileInfo source, FileInfo target, uint uid = 0, uint gid = 0, UnixFileModes fileMode = Unix.FileMode644)
     {
       using (var fileStream = source.Open(FileMode.Open, FileAccess.Read, FileShare.ReadWrite))
       {
         using (var streamReader = new BinaryReader(fileStream))
         {
           var resourceContent = streamReader.ReadBytes((int)streamReader.BaseStream.Length);
-          return WithResourceMapping(resourceContent, target.ToString(), fileMode);
+          return WithResourceMapping(resourceContent, target.ToString(), uid, gid, fileMode);
         }
       }
     }
 
     /// <inheritdoc />
-    public TBuilderEntity WithResourceMapping(Uri source, string target, UnixFileModes fileMode = Unix.FileMode644)
+    public TBuilderEntity WithResourceMapping(Uri source, string target, uint uid = 0, uint gid = 0, UnixFileModes fileMode = Unix.FileMode644)
     {
       if (source.IsFile)
       {
-        return WithResourceMapping(new FileResourceMapping(source.AbsolutePath, target, fileMode));
+        return WithResourceMapping(new FileResourceMapping(source.AbsolutePath, target, uid, gid, fileMode));
       }
       else
       {
-        return WithResourceMapping(new UriResourceMapping(source, target, fileMode));
+        return WithResourceMapping(new UriResourceMapping(source, target, uid, gid, fileMode));
       }
     }