Add PostgreSQL SSL configuration example and tests

Directory.Build.props

@@ -21,10 +21,14 @@
     <RepositoryUrl>https://github.com/testcontainers/testcontainers-dotnet</RepositoryUrl>
   </PropertyGroup>
   <PropertyGroup>
-    <AssemblyOriginatorKeyFile>$(MSBuildThisFileDirectory)src/strongname.snk</AssemblyOriginatorKeyFile>
-    <SignAssembly>true</SignAssembly>
+    <!-- Enable signing only in CI or when explicitly requested -->
+    <SignAssembly Condition="'$(SIGN_ASSEMBLY)' == 'true' or '$(CI)' == 'true'">true</SignAssembly>
+    <SignAssembly Condition="'$(SignAssembly)' == ''">false</SignAssembly>
     <DebugType>embedded</DebugType>
   </PropertyGroup>
+  <PropertyGroup Condition="'$(SignAssembly)' == 'true'">
+    <AssemblyOriginatorKeyFile>$(MSBuildThisFileDirectory)src/strongname.snk</AssemblyOriginatorKeyFile>
+  </PropertyGroup>
   <PropertyGroup>
     <NoWarn>CA1859,CA1861,CS0618,CS1591,xUnit1044,xUnit1045</NoWarn>
   </PropertyGroup>
@@ -41,9 +45,14 @@
     <None Include="$(MSBuildThisFileDirectory)LICENSE" Visible="false" Pack="true" PackagePath="" />
     <None Include="$(MSBuildThisFileDirectory)README.md" Visible="false" Pack="true" PackagePath="" />
   </ItemGroup>
-  <ItemGroup>
+  <ItemGroup Condition="'$(SignAssembly)' == 'true'">
     <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
       <_Parameter1>Testcontainers.Tests, PublicKey=$([System.IO.File]::ReadAllText($(MSBuildThisFileDirectory)src/strongname.pub))</_Parameter1>
     </AssemblyAttribute>
   </ItemGroup>
+  <ItemGroup Condition="'$(SignAssembly)' != 'true'">
+    <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
+      <_Parameter1>Testcontainers.Tests</_Parameter1>
+    </AssemblyAttribute>
+  </ItemGroup>
 </Project>

docs/modules/postgres.md

@@ -32,4 +32,32 @@ The test example uses the following NuGet dependencies:
 
 To execute the tests, use the command `dotnet test` from a terminal.
 
---8<-- "docs/modules/_call_out_test_projects.txt"
+## Enable SSL/TLS
+
+The PostgreSQL module supports configuring server-side SSL. Provide paths to your CA certificate, server certificate, and server private key when building the container:
+
+```csharp
+var postgreSqlContainer = new PostgreSqlBuilder()
+    .WithSSLSettings("/path/to/ca_cert.pem",
+                     "/path/to/server.crt",
+                     "/path/to/server.key")
+    .Build();
+await postgreSqlContainer.StartAsync();
+```
+
+When connecting with Npgsql during tests, you can require SSL and (optionally) trust the test certificate:
+
+```csharp
+var csb = new Npgsql.NpgsqlConnectionStringBuilder(postgreSqlContainer.GetConnectionString())
+{
+    SslMode = Npgsql.SslMode.Require,
+    // For testing only; prefer proper CA validation in production.
+    TrustServerCertificate = true
+};
+await using var connection = new Npgsql.NpgsqlConnection(csb.ConnectionString);
+await connection.OpenAsync();
+```
+
+For production scenarios, validate the server certificate against a trusted CA instead of using TrustServerCertificate.
+
+--8<-- "docs/modules/_call_out_test_projects.txt"

src/Testcontainers.PostgreSql/PostgreSqlBuilder.cs

@@ -2,7 +2,8 @@ namespace Testcontainers.PostgreSql;
 
 /// <inheritdoc cref="ContainerBuilder{TBuilderEntity, TContainerEntity, TConfigurationEntity}" />
 [PublicAPI]
-public sealed class PostgreSqlBuilder : ContainerBuilder<PostgreSqlBuilder, PostgreSqlContainer, PostgreSqlConfiguration>
+public sealed class
+    PostgreSqlBuilder : ContainerBuilder<PostgreSqlBuilder, PostgreSqlContainer, PostgreSqlConfiguration>
 {
     public const string PostgreSqlImage = "postgres:15.1";
 
@@ -14,6 +15,8 @@ public sealed class PostgreSqlBuilder : ContainerBuilder<PostgreSqlBuilder, Post
 
     public const string DefaultPassword = "postgres";
 
+    private const string DefaultCertificatesDirectory = "/var/lib/postgresql/certs";
+
     /// <summary>
     /// Initializes a new instance of the <see cref="PostgreSqlBuilder" /> class.
     /// </summary>
@@ -69,14 +72,122 @@ public PostgreSqlBuilder WithPassword(string password)
             .WithEnvironment("POSTGRES_PASSWORD", password);
     }
 
+    /// <summary>
+    /// Sets the PostgreSql SSL mode.
+    /// </summary>
+    /// <param name="sslMode">The PostgreSql SSL mode.</param>
+    /// <returns>A configured instance of <see cref="PostgreSqlBuilder" />.</returns>
+    public PostgreSqlBuilder WithSslMode(SslMode sslMode)
+    {
+        return Merge(DockerResourceConfiguration, new PostgreSqlConfiguration(sslMode: sslMode))
+            .WithEnvironment("PGSSLMODE", sslMode.ToString().ToLowerInvariant());
+    }
+
+    /// <summary>
+    /// Sets the PostgreSql root certificate file.
+    /// </summary>
+    /// <param name="rootCertFile">The path to the root certificate file.</param>
+    /// <returns>A configured instance of <see cref="PostgreSqlBuilder" />.</returns>
+    public PostgreSqlBuilder WithRootCertificate(string rootCertFile)
+    {
+        return Merge(DockerResourceConfiguration, new PostgreSqlConfiguration(rootCertFile: rootCertFile))
+            .WithBindMount(rootCertFile, Path.Combine(DefaultCertificatesDirectory, "root.crt"), AccessMode.ReadOnly)
+            .WithEnvironment("PGSSLROOTCERT", Path.Combine(DefaultCertificatesDirectory, "root.crt"));
+    }
+
+    /// <summary>
+    /// Sets the PostgreSql client certificate and key files.
+    /// </summary>
+    /// <param name="clientCertFile">The path to the client certificate file.</param>
+    /// <param name="clientKeyFile">The path to the client key file.</param>
+    /// <returns>A configured instance of <see cref="PostgreSqlBuilder" />.</returns>
+    public PostgreSqlBuilder WithClientCertificate(string clientCertFile, string clientKeyFile)
+    {
+        return Merge(DockerResourceConfiguration,
+                new PostgreSqlConfiguration(clientCertFile: clientCertFile, clientKeyFile: clientKeyFile))
+            .WithBindMount(clientCertFile, Path.Combine(DefaultCertificatesDirectory, "postgresql.crt"),
+                AccessMode.ReadOnly)
+            .WithBindMount(clientKeyFile, Path.Combine(DefaultCertificatesDirectory, "postgresql.key"),
+                AccessMode.ReadOnly)
+            .WithEnvironment("PGSSLCERT", Path.Combine(DefaultCertificatesDirectory, "postgresql.crt"))
+            .WithEnvironment("PGSSLKEY", Path.Combine(DefaultCertificatesDirectory, "postgresql.key"));
+    }
+
+    /// <summary>
+    /// Configures the PostgreSQL server to run with SSL using the provided CA certificate, server certificate and private key.
+    /// This enables server-side SSL configuration with client certificate authentication.
+    /// </summary>
+    /// <param name="caCertFile">The path to the CA certificate file.</param>
+    /// <param name="serverCertFile">The path to the server certificate file.</param>
+    /// <param name="serverKeyFile">The path to the server private key file.</param>
+    /// <returns>A configured instance of <see cref="PostgreSqlBuilder" />.</returns>
+    /// <remarks>
+    /// This method configures PostgreSQL for server-side SSL with client certificate authentication.
+    /// It requires a custom PostgreSQL configuration file that enables SSL and sets the appropriate
+    /// certificate paths. The certificates are mounted into the container and PostgreSQL is configured
+    /// to use them for SSL connections.
+    /// </remarks>
+    public PostgreSqlBuilder WithSSLSettings(string caCertFile, string serverCertFile, string serverKeyFile)
+    {
+        if (string.IsNullOrWhiteSpace(caCertFile))
+        {
+            throw new ArgumentException("CA certificate file path cannot be null or empty.", nameof(caCertFile));
+        }
+
+        if (string.IsNullOrWhiteSpace(serverCertFile))
+        {
+            throw new ArgumentException("Server certificate file path cannot be null or empty.",
+                nameof(serverCertFile));
+        }
+
+        if (string.IsNullOrWhiteSpace(serverKeyFile))
+        {
+            throw new ArgumentException("Server key file path cannot be null or empty.", nameof(serverKeyFile));
+        }
+
+        const string sslConfigDir = "/tmp/testcontainers-dotnet/postgres";
+
+        var wrapperEntrypoint = @"#!/bin/sh
+set -e
+SSL_DIR=/tmp/testcontainers-dotnet/postgres
+# Fix ownership and permissions for SSL key/cert before Postgres init runs
+if [ -f ""$SSL_DIR/server.key"" ]; then
+  chown postgres:postgres ""$SSL_DIR/server.key"" || true
+  chmod 600 ""$SSL_DIR/server.key"" || true
+fi
+if [ -f ""$SSL_DIR/server.crt"" ]; then
+  chown postgres:postgres ""$SSL_DIR/server.crt"" || true
+fi
+if [ -f ""$SSL_DIR/ca_cert.pem"" ]; then
+  chown postgres:postgres ""$SSL_DIR/ca_cert.pem"" || true
+fi
+exec /usr/local/bin/docker-entrypoint.sh ""$@""
+";
+
+        return Merge(DockerResourceConfiguration, new PostgreSqlConfiguration(
+                serverCertFile: serverCertFile,
+                serverKeyFile: serverKeyFile,
+                caCertFile: caCertFile))
+            .WithResourceMapping(File.ReadAllBytes(caCertFile), $"{sslConfigDir}/ca_cert.pem", fileMode: Unix.FileMode644)
+            .WithResourceMapping(File.ReadAllBytes(serverCertFile), $"{sslConfigDir}/server.crt", fileMode: Unix.FileMode644)
+            .WithResourceMapping(File.ReadAllBytes(serverKeyFile), $"{sslConfigDir}/server.key", fileMode: Unix.FileMode700)
+            .WithResourceMapping(Encoding.UTF8.GetBytes(wrapperEntrypoint), "/usr/local/bin/docker-entrypoint-ssl.sh", fileMode: Unix.FileMode755)
+            .WithEntrypoint("/usr/local/bin/docker-entrypoint-ssl.sh")
+            .WithCommand("-c", "ssl=on")
+            .WithCommand("-c", $"ssl_ca_file={sslConfigDir}/ca_cert.pem")
+            .WithCommand("-c", $"ssl_cert_file={sslConfigDir}/server.crt")
+            .WithCommand("-c", $"ssl_key_file={sslConfigDir}/server.key");
+    }
+
     /// <inheritdoc />
     public override PostgreSqlContainer Build()
     {
         Validate();
 
-        // By default, the base builder waits until the container is running. However, for PostgreSql, a more advanced waiting strategy is necessary that requires access to the configured database and username.
-        // If the user does not provide a custom waiting strategy, append the default PostgreSql waiting strategy.
-        var postgreSqlBuilder = DockerResourceConfiguration.WaitStrategies.Count() > 1 ? this : WithWaitStrategy(Wait.ForUnixContainer().AddCustomWaitStrategy(new WaitUntil(DockerResourceConfiguration)));
+        // Ensure PostgreSQL is actually ready to accept connections over TCP, not just that the container is running.
+        // Always append the pg_isready-based wait strategy by default so tests using the default fixture are stable.
+        var postgreSqlBuilder =
+            WithWaitStrategy(Wait.ForUnixContainer().AddCustomWaitStrategy(new WaitUntil(DockerResourceConfiguration)));
         return new PostgreSqlContainer(postgreSqlBuilder.DockerResourceConfiguration);
     }
 
@@ -135,7 +246,11 @@ private sealed class WaitUntil : IWaitUntil
         public WaitUntil(PostgreSqlConfiguration configuration)
         {
             // Explicitly specify the host to ensure readiness only after the initdb scripts have executed, and the server is listening on TCP/IP.
-            _command = new List<string> { "pg_isready", "--host", "localhost", "--dbname", configuration.Database, "--username", configuration.Username };
+            _command = new List<string>
+            {
+                "pg_isready", "--host", "localhost", "--dbname", configuration.Database, "--username",
+                configuration.Username
+            };
         }
 
         /// <summary>
@@ -154,7 +269,8 @@ public async Task<bool> UntilAsync(IContainer container)
 
             if (execResult.Stderr.Contains("pg_isready was not found"))
             {
-                throw new NotSupportedException($"The '{container.Image.FullName}' image does not contain: pg_isready. Please use 'postgres:9.3' onwards.");
+                throw new NotSupportedException(
+                    $"The '{container.Image.FullName}' image does not contain: pg_isready. Please use 'postgres:9.3' onwards.");
             }
 
             return 0L.Equals(execResult.ExitCode);

src/Testcontainers.PostgreSql/PostgreSqlConfiguration.cs

@@ -10,14 +10,35 @@ public sealed class PostgreSqlConfiguration : ContainerConfiguration
     /// <param name="database">The PostgreSql database.</param>
     /// <param name="username">The PostgreSql username.</param>
     /// <param name="password">The PostgreSql password.</param>
+    /// <param name="sslMode">The PostgreSql SSL mode.</param>
+    /// <param name="rootCertFile">The path to the PostgreSql root certificate file.</param>
+    /// <param name="clientCertFile">The path to the PostgreSql client certificate file.</param>
+    /// <param name="clientKeyFile">The path to the PostgreSql client key file.</param>
+    /// <param name="serverCertFile">The path to the PostgreSql server certificate file.</param>
+    /// <param name="serverKeyFile">The path to the PostgreSql server key file.</param>
+    /// <param name="caCertFile">The path to the PostgreSql CA certificate file.</param>
     public PostgreSqlConfiguration(
         string database = null,
         string username = null,
-        string password = null)
+        string password = null,
+        SslMode? sslMode = null,
+        string rootCertFile = null,
+        string clientCertFile = null,
+        string clientKeyFile = null,
+        string serverCertFile = null,
+        string serverKeyFile = null,
+        string caCertFile = null)
     {
         Database = database;
         Username = username;
         Password = password;
+        SslMode = sslMode;
+        RootCertFile = rootCertFile;
+        ClientCertFile = clientCertFile;
+        ClientKeyFile = clientKeyFile;
+        ServerCertFile = serverCertFile;
+        ServerKeyFile = serverKeyFile;
+        CaCertFile = caCertFile;
     }
 
     /// <summary>
@@ -61,6 +82,13 @@ public PostgreSqlConfiguration(PostgreSqlConfiguration oldValue, PostgreSqlConfi
         Database = BuildConfiguration.Combine(oldValue.Database, newValue.Database);
         Username = BuildConfiguration.Combine(oldValue.Username, newValue.Username);
         Password = BuildConfiguration.Combine(oldValue.Password, newValue.Password);
+        SslMode = BuildConfiguration.Combine(oldValue.SslMode, newValue.SslMode);
+        RootCertFile = BuildConfiguration.Combine(oldValue.RootCertFile, newValue.RootCertFile);
+        ClientCertFile = BuildConfiguration.Combine(oldValue.ClientCertFile, newValue.ClientCertFile);
+        ClientKeyFile = BuildConfiguration.Combine(oldValue.ClientKeyFile, newValue.ClientKeyFile);
+        ServerCertFile = BuildConfiguration.Combine(oldValue.ServerCertFile, newValue.ServerCertFile);
+        ServerKeyFile = BuildConfiguration.Combine(oldValue.ServerKeyFile, newValue.ServerKeyFile);
+        CaCertFile = BuildConfiguration.Combine(oldValue.CaCertFile, newValue.CaCertFile);
     }
 
     /// <summary>
@@ -77,4 +105,39 @@ public PostgreSqlConfiguration(PostgreSqlConfiguration oldValue, PostgreSqlConfi
     /// Gets the PostgreSql password.
     /// </summary>
     public string Password { get; }
+
+    /// <summary>
+    /// Gets the PostgreSql SSL mode.
+    /// </summary>
+    public SslMode? SslMode { get; }
+
+    /// <summary>
+    /// Gets the path to the PostgreSql root certificate file.
+    /// </summary>
+    public string RootCertFile { get; }
+
+    /// <summary>
+    /// Gets the path to the PostgreSql client certificate file.
+    /// </summary>
+    public string ClientCertFile { get; }
+
+    /// <summary>
+    /// Gets the path to the PostgreSql client key file.
+    /// </summary>
+    public string ClientKeyFile { get; }
+
+    /// <summary>
+    /// Gets the path to the PostgreSql server certificate file.
+    /// </summary>
+    public string ServerCertFile { get; }
+
+    /// <summary>
+    /// Gets the path to the PostgreSql server key file.
+    /// </summary>
+    public string ServerKeyFile { get; }
+
+    /// <summary>
+    /// Gets the path to the PostgreSql CA certificate file.
+    /// </summary>
+    public string CaCertFile { get; }
 }

src/Testcontainers.PostgreSql/PostgreSqlContainer.cs

@@ -44,7 +44,7 @@ public async Task<ExecResult> ExecScriptAsync(string scriptContent, Cancellation
         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)
+        return await ExecAsync(new[] { "psql", "--host", "localhost", "--username", _configuration.Username, "--dbname", _configuration.Database, "--file", scriptFilePath }, ct)
             .ConfigureAwait(false);
     }
 }

src/Testcontainers.PostgreSql/SslMode.cs

@@ -0,0 +1,27 @@
+namespace Testcontainers.PostgreSql;
+
+/// <summary>
+/// Represents the SSL mode for PostgreSQL connections.
+/// </summary>
+public enum SslMode
+{
+    /// <summary>
+    /// SSL is disabled.
+    /// </summary>
+    Disable,
+
+    /// <summary>
+    /// SSL is required.
+    /// </summary>
+    Require,
+
+    /// <summary>
+    /// SSL is required, and the server certificate is verified against the root certificate.
+    /// </summary>
+    VerifyCa,
+
+    /// <summary>
+    /// SSL is required, and the server certificate is verified against the root certificate and the common name.
+    /// </summary>
+    VerifyFull
+}