or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

access-methods.mdconfiguration.mddeprecated-api.mdindex.md
tile.json

configuration.mddocs/

Container Configuration

Configure RabbitMQ containers with custom credentials, SSL/TLS certificates, and configuration files. All configuration methods use the fluent builder pattern, returning the container instance for method chaining.

Important Notes for Agents

  • All configuration methods must be called before start()
  • Configuration is immutable after container starts
  • Fluent API allows method chaining for multiple configurations
  • File paths must be valid and accessible at container startup time
  • SSL configuration requires all three certificate files (key, cert, CA)
  • Configuration files must be valid RabbitMQ format (sysctl or erlang)
  • Credentials are applied during container startup
  • Environment variables can be set using inherited withEnv() method
  • Configuration order does not matter (all applied before startup)
  • Multiple calls to same configuration method: last call wins
  • Configuration methods return RabbitMQContainer for method chaining
  • Invalid configuration may cause container startup failures
  • File resources must exist and be readable at configuration time

Capabilities

Admin Credentials

Configure the RabbitMQ admin username and password. Default credentials are "guest"/"guest".

/**
 * Sets the username for the admin account.
 * @param adminUsername The admin username (default is "guest")
 * @return This container for method chaining
 */
public RabbitMQContainer withAdminUser(String adminUsername)

/**
 * Sets the password for the admin account.
 * @param adminPassword The admin password (default is "guest")
 * @return This container for method chaining
 */
public RabbitMQContainer withAdminPassword(String adminPassword)

/**
 * Returns the admin username.
 * @return The admin username
 */
public String getAdminUsername()

/**
 * Returns the admin password.
 * @return The admin password
 */
public String getAdminPassword()

Usage Example:

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withAdminUser("admin")
    .withAdminPassword("secretpassword");

rabbitmq.start();

String username = rabbitmq.getAdminUsername();  // "admin"
String password = rabbitmq.getAdminPassword();  // "secretpassword"

Error Handling:

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withAdminUser("admin")
    .withAdminPassword("secretpassword");

try {
    rabbitmq.start();
    
    // Verify credentials work
    ConnectionFactory factory = new ConnectionFactory();
    factory.setUri(rabbitmq.getAmqpUrl());
    factory.setUsername(rabbitmq.getAdminUsername());
    factory.setPassword(rabbitmq.getAdminPassword());
    
    try (Connection conn = factory.newConnection()) {
        // Credentials are valid
    }
} catch (Exception e) {
    // Authentication failed - check credentials
    System.err.println("Failed to authenticate: " + e.getMessage());
    throw e;
}

Configuration After Start (Invalid):

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"));
rabbitmq.start();

// This has no effect - configuration must be set before start()
rabbitmq.withAdminUser("newuser");  // Ignored

Multiple Configuration Calls:

// Last call wins for same configuration type
RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withAdminUser("user1")
    .withAdminUser("user2");  // user2 is used

rabbitmq.start();
String username = rabbitmq.getAdminUsername();  // "user2"

Null Credentials:

// Null username or password may cause container startup failures
// Always provide non-null values
RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withAdminUser("admin")
    .withAdminPassword("");  // Empty password may work but not recommended

SSL/TLS Configuration

Enable SSL/TLS for secure AMQP and management connections. Requires server key, certificate, and CA certificate files.

/**
 * Configures SSL/TLS for RabbitMQ connections with basic verification settings.
 * @param keyFile Server private key file
 * @param certFile Server certificate file
 * @param caFile CA certificate file
 * @param verify SSL verification mode (VERIFY_NONE or VERIFY_PEER)
 * @return This container for method chaining
 */
public RabbitMQContainer withSSL(
    MountableFile keyFile,
    MountableFile certFile,
    MountableFile caFile,
    SslVerification verify
)

/**
 * Configures SSL/TLS with peer certificate requirement setting.
 * @param keyFile Server private key file
 * @param certFile Server certificate file
 * @param caFile CA certificate file
 * @param verify SSL verification mode (VERIFY_NONE or VERIFY_PEER)
 * @param failIfNoCert Whether to fail if no peer certificate is provided
 * @return This container for method chaining
 */
public RabbitMQContainer withSSL(
    MountableFile keyFile,
    MountableFile certFile,
    MountableFile caFile,
    SslVerification verify,
    boolean failIfNoCert
)

/**
 * Configures SSL/TLS with full control over verification parameters.
 * @param keyFile Server private key file
 * @param certFile Server certificate file
 * @param caFile CA certificate file
 * @param verify SSL verification mode (VERIFY_NONE or VERIFY_PEER)
 * @param failIfNoCert Whether to fail if no peer certificate is provided
 * @param verificationDepth Maximum certificate chain verification depth
 * @return This container for method chaining
 */
public RabbitMQContainer withSSL(
    MountableFile keyFile,
    MountableFile certFile,
    MountableFile caFile,
    SslVerification verify,
    boolean failIfNoCert,
    int verificationDepth
)

/**
 * SSL verification modes for RabbitMQ connections.
 */
public enum SslVerification {
    /** Disables SSL peer verification */
    VERIFY_NONE,
    /** Enables SSL peer verification */
    VERIFY_PEER
}

Basic SSL Usage Example:

import org.testcontainers.utility.MountableFile;
import org.testcontainers.containers.RabbitMQContainer.SslVerification;

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withSSL(
        MountableFile.forClasspathResource("certs/server_key.pem"),
        MountableFile.forClasspathResource("certs/server_certificate.pem"),
        MountableFile.forClasspathResource("certs/ca_certificate.pem"),
        SslVerification.VERIFY_PEER
    );

rabbitmq.start();

// Connect using AMQPS
String amqpsUrl = rabbitmq.getAmqpsUrl();  // "amqps://host:port"

Complete SSL Setup with Client Configuration:

import org.testcontainers.utility.MountableFile;
import org.testcontainers.containers.RabbitMQContainer.SslVerification;
import com.rabbitmq.client.ConnectionFactory;
import com.rabbitmq.client.Connection;
import com.rabbitmq.client.Channel;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManagerFactory;
import java.io.FileInputStream;
import java.security.KeyStore;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;

// Configure container SSL
RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withSSL(
        MountableFile.forClasspathResource("certs/server_key.pem"),
        MountableFile.forClasspathResource("certs/server_certificate.pem"),
        MountableFile.forClasspathResource("certs/ca_certificate.pem"),
        SslVerification.VERIFY_PEER
    );

rabbitmq.start();

// Setup SSL context for client
CertificateFactory cf = CertificateFactory.getInstance("X.509");
X509Certificate caCert = (X509Certificate) cf.generateCertificate(
    new FileInputStream("src/test/resources/certs/ca_certificate.pem"));

KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
keyStore.load(null, null);
keyStore.setCertificateEntry("ca", caCert);

TrustManagerFactory tmf = TrustManagerFactory.getInstance(
    TrustManagerFactory.getDefaultAlgorithm());
tmf.init(keyStore);

SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
sslContext.init(null, tmf.getTrustManagers(), null);

// Configure connection factory
ConnectionFactory factory = new ConnectionFactory();
factory.setUri(rabbitmq.getAmqpsUrl());
factory.useSslProtocol(sslContext);
factory.setUsername(rabbitmq.getAdminUsername());
factory.setPassword(rabbitmq.getAdminPassword());
factory.setConnectionTimeout(5000);

try (Connection connection = factory.newConnection();
     Channel channel = connection.createChannel()) {
    // Use secure connection
    channel.queueDeclare("secure-queue", false, false, false, null);
}

Advanced SSL Configuration:

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withSSL(
        MountableFile.forClasspathResource("certs/server_key.pem"),
        MountableFile.forClasspathResource("certs/server_certificate.pem"),
        MountableFile.forClasspathResource("certs/ca_certificate.pem"),
        SslVerification.VERIFY_PEER,
        true,   // failIfNoCert - require client certificate
        10      // verificationDepth - max chain depth
    );

SSL Error Handling:

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"));

try {
    rabbitmq.withSSL(
        MountableFile.forClasspathResource("certs/server_key.pem"),
        MountableFile.forClasspathResource("certs/server_certificate.pem"),
        MountableFile.forClasspathResource("certs/ca_certificate.pem"),
        SslVerification.VERIFY_PEER
    );
    rabbitmq.start();
} catch (Exception e) {
    if (e.getMessage().contains("certificate") || 
        e.getMessage().contains("SSL") ||
        e.getMessage().contains("TLS")) {
        // SSL configuration issue
        // Check: certificate files exist, are valid, and accessible
        // Check: certificate format is correct (PEM)
        // Check: certificate chain is valid
        System.err.println("SSL configuration failed: " + e.getMessage());
    }
    throw e;
}

SSL with File System Paths:

// Use file system paths instead of classpath resources
RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withSSL(
        MountableFile.forHostPath("/path/to/server_key.pem"),
        MountableFile.forHostPath("/path/to/server_certificate.pem"),
        MountableFile.forHostPath("/path/to/ca_certificate.pem"),
        SslVerification.VERIFY_PEER
    );

SSL Verification Modes:

// VERIFY_NONE: No peer certificate verification (less secure, for testing)
RabbitMQContainer rabbitmq1 = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withSSL(
        MountableFile.forClasspathResource("certs/server_key.pem"),
        MountableFile.forClasspathResource("certs/server_certificate.pem"),
        MountableFile.forClasspathResource("certs/ca_certificate.pem"),
        SslVerification.VERIFY_NONE  // No verification
    );

// VERIFY_PEER: Full peer certificate verification (recommended)
RabbitMQContainer rabbitmq2 = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withSSL(
        MountableFile.forClasspathResource("certs/server_key.pem"),
        MountableFile.forClasspathResource("certs/server_certificate.pem"),
        MountableFile.forClasspathResource("certs/ca_certificate.pem"),
        SslVerification.VERIFY_PEER  // Full verification
    );

Configuration Files

Mount custom RabbitMQ configuration files to override default settings. Supports both sysctl format (recommended for RabbitMQ >= 3.7) and erlang format.

/**
 * Overwrites the default RabbitMQ configuration file with the supplied one in sysctl format.
 * Note: Don't forget to include an empty line at the end of the file.
 * @param rabbitMQConf The rabbitmq.conf file to use (sysctl format)
 * @return This container for method chaining
 */
public RabbitMQContainer withRabbitMQConfig(MountableFile rabbitMQConf)

/**
 * Overwrites the default RabbitMQ configuration file with sysctl format.
 * This function doesn't work with RabbitMQ < 3.7.
 * This function and the sysctl format is recommended for RabbitMQ >= 3.7.
 * Note: Don't forget to include an empty line at the end of the file.
 * @param rabbitMQConf The rabbitmq.conf file to use (sysctl format)
 * @return This container for method chaining
 */
public RabbitMQContainer withRabbitMQConfigSysctl(MountableFile rabbitMQConf)

/**
 * Overwrites the default RabbitMQ configuration file with erlang format.
 * @param rabbitMQConf The rabbitmq.config file to use (erlang format)
 * @return This container for method chaining
 */
public RabbitMQContainer withRabbitMQConfigErlang(MountableFile rabbitMQConf)

Usage Example (Sysctl Format):

Create a configuration file src/test/resources/rabbitmq-custom.conf:

# Enable debug logging
log.console.level = debug

# Set memory threshold
vm_memory_high_watermark.relative = 0.6

# Set disk free limit
disk_free_limit.absolute = 2GB

# Note: Empty line required at end of file

Use in test:

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withRabbitMQConfig(
        MountableFile.forClasspathResource("rabbitmq-custom.conf"));

rabbitmq.start();

// Configuration is applied, check logs
String logs = rabbitmq.getLogs();
assert logs.contains("debug") || logs.contains("Debug");

Usage Example (Erlang Format):

Create a configuration file src/test/resources/rabbitmq-custom.config:

[
  {rabbit, [
    {log, [
      {console, [{level, debug}]}
    ]},
    {vm_memory_high_watermark, 0.6}
  ]}
].

Use in test:

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withRabbitMQConfigErlang(
        MountableFile.forClasspathResource("rabbitmq-custom.config"));

rabbitmq.start();

Configuration File Error Handling:

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"));

try {
    rabbitmq.withRabbitMQConfig(
        MountableFile.forClasspathResource("rabbitmq-custom.conf"));
    rabbitmq.start();
    
    // Verify configuration applied
    String logs = rabbitmq.getLogs();
    // Check for expected configuration effects
    
} catch (Exception e) {
    if (e.getMessage().contains("config") || 
        e.getMessage().contains("syntax") ||
        e.getMessage().contains("parse")) {
        // Configuration file issue
        // Check: file exists and is readable
        // Check: file format is correct (sysctl or erlang)
        // Check: sysctl format has empty line at end
        // Check: erlang format is valid Erlang syntax
        System.err.println("Configuration file error: " + e.getMessage());
    }
    throw e;
}

Common Configuration Options (Sysctl Format):

# Logging
log.console.level = info
log.console = true
log.file = false

# Memory
vm_memory_high_watermark.relative = 0.6
vm_memory_high_watermark_paging_ratio = 0.5

# Disk
disk_free_limit.absolute = 2GB
disk_free_limit.relative = 1.0

# Network
listeners.tcp.default = 5672
listeners.ssl.default = 5671

# Management
management.tcp.port = 15672
management.ssl.port = 15671

# Note: Empty line required at end

Configuration File Format Requirements:

// Sysctl format requires empty line at end
// Valid:
// log.console.level = debug
// (empty line)

// Invalid (missing empty line):
// log.console.level = debug
// (no empty line - may cause parsing errors)

// Erlang format must be valid Erlang syntax
// Valid:
// [
//   {rabbit, [
//     {log, [{console, [{level, debug}]}]}
//   ]}
// ].

// Invalid (syntax error):
// [
//   {rabbit, [
//     {log, [{console, [{level, debug}]}]}  // Missing closing bracket
//   ]}
// ].

Combined Configuration Example

import org.testcontainers.containers.RabbitMQContainer;
import org.testcontainers.containers.RabbitMQContainer.SslVerification;
import org.testcontainers.utility.MountableFile;
import org.testcontainers.utility.DockerImageName;

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withAdminUser("testuser")
    .withAdminPassword("testpass")
    .withSSL(
        MountableFile.forClasspathResource("certs/server_key.pem"),
        MountableFile.forClasspathResource("certs/server_certificate.pem"),
        MountableFile.forClasspathResource("certs/ca_certificate.pem"),
        SslVerification.VERIFY_PEER
    )
    .withRabbitMQConfig(
        MountableFile.forClasspathResource("rabbitmq-custom.conf"))
    .withEnv("RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS", "-smp disable");

rabbitmq.start();

// Fully configured RabbitMQ container ready for testing

Environment Variables

Use inherited withEnv() method to set RabbitMQ environment variables:

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withEnv("RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS", "-smp disable")
    .withEnv("RABBITMQ_VM_MEMORY_HIGH_WATERMARK", "0.6");

rabbitmq.start();

Common Environment Variables:

// Erlang VM arguments
.withEnv("RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS", "-smp disable")

// Memory watermark
.withEnv("RABBITMQ_VM_MEMORY_HIGH_WATERMARK", "0.6")

// Disk free limit
.withEnv("RABBITMQ_DISK_FREE_LIMIT", "2GB")

// Log level
.withEnv("RABBITMQ_LOG_LEVEL", "debug")

Edge Cases

Missing Certificate Files

try {
    rabbitmq.withSSL(
        MountableFile.forClasspathResource("nonexistent_key.pem"),
        MountableFile.forClasspathResource("nonexistent_cert.pem"),
        MountableFile.forClasspathResource("nonexistent_ca.pem"),
        SslVerification.VERIFY_PEER
    );
    rabbitmq.start();
} catch (Exception e) {
    // File not found or not accessible
    // Ensure certificate files exist in classpath or file system
    if (e.getMessage().contains("not found") || 
        e.getMessage().contains("cannot be read")) {
        System.err.println("Certificate file not found: " + e.getMessage());
    }
    throw e;
}

Invalid Configuration File Format

// Sysctl format without empty line at end
// rabbitmq-custom.conf:
// log.console.level = debug
// (missing empty line)

try {
    rabbitmq.withRabbitMQConfig(
        MountableFile.forClasspathResource("rabbitmq-custom.conf"));
    rabbitmq.start();
} catch (Exception e) {
    // Configuration parsing may fail
    // Always include empty line at end of sysctl format files
    if (e.getMessage().contains("parse") || 
        e.getMessage().contains("syntax")) {
        System.err.println("Configuration parsing failed: " + e.getMessage());
    }
    throw e;
}

Configuration After Start

RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"));
rabbitmq.start();

// These have no effect - configuration must be set before start()
rabbitmq.withAdminUser("newuser");  // Ignored
rabbitmq.withAdminPassword("newpass");  // Ignored
rabbitmq.withSSL(...);  // Ignored

Multiple Configuration Calls

// Last call wins for same configuration type
RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withAdminUser("user1")
    .withAdminUser("user2");  // user2 is used

rabbitmq.start();
String username = rabbitmq.getAdminUsername();  // "user2"

Invalid SSL Certificate Format

try {
    rabbitmq.withSSL(
        MountableFile.forClasspathResource("invalid_key.pem"),  // Not a valid PEM
        MountableFile.forClasspathResource("invalid_cert.pem"),  // Not a valid certificate
        MountableFile.forClasspathResource("invalid_ca.pem"),  // Not a valid CA
        SslVerification.VERIFY_PEER
    );
    rabbitmq.start();
} catch (Exception e) {
    // Invalid certificate format causes startup failure
    if (e.getMessage().contains("certificate") || 
        e.getMessage().contains("SSL") ||
        e.getMessage().contains("TLS")) {
        System.err.println("Invalid certificate format: " + e.getMessage());
    }
    throw e;
}

Configuration File with Invalid Syntax

// Erlang format with syntax errors
try {
    rabbitmq.withRabbitMQConfigErlang(
        MountableFile.forClasspathResource("invalid-syntax.config"));
    rabbitmq.start();
} catch (Exception e) {
    // Erlang syntax errors cause startup failure
    if (e.getMessage().contains("syntax") || 
        e.getMessage().contains("parse")) {
        System.err.println("Invalid Erlang syntax: " + e.getMessage());
    }
    throw e;
}

Large Configuration Files

// Large configuration files may slow container startup
RabbitMQContainer rabbitmq = new RabbitMQContainer(
    DockerImageName.parse("rabbitmq:3.7.25-management-alpine"))
    .withRabbitMQConfig(
        MountableFile.forClasspathResource("large-config.conf"));  // Large file

// Consider increasing startup timeout for large configs
rabbitmq.withStartupTimeout(Duration.ofMinutes(2));
rabbitmq.start();

Configuration File Path Issues

// File path must be accessible at configuration time
try {
    rabbitmq.withRabbitMQConfig(
        MountableFile.forClasspathResource("config/rabbitmq.conf"));  // Must exist
    rabbitmq.start();
} catch (Exception e) {
    if (e.getMessage().contains("not found") || 
        e.getMessage().contains("cannot be read")) {
        // File path issue - check file exists and is readable
        System.err.println("Configuration file not found: " + e.getMessage());
    }
    throw e;
}

Notes

  • All configuration methods use fluent API pattern for method chaining
  • Configuration is applied during container startup, not at configuration time
  • Invalid configuration may cause container startup failures (check logs for details)
  • File resources are copied into container at startup time
  • Configuration files override default RabbitMQ settings
  • Environment variables can be used in addition to configuration files
  • SSL configuration requires all three certificate files (key, cert, CA)
  • Sysctl format is recommended for RabbitMQ >= 3.7
  • Erlang format works with all RabbitMQ versions but is more complex
  • Configuration order does not matter (all applied before startup)
  • Multiple calls to same configuration method: last call wins
  • Configuration cannot be changed after container starts
  • Use getAdminUsername() and getAdminPassword() to retrieve configured credentials
  • SSL configuration enables AMQPS and HTTPS endpoints
  • Configuration files must be valid RabbitMQ format (sysctl or erlang)
  • Empty line required at end of sysctl format files
  • Erlang format files must be valid Erlang syntax
  • File paths must be accessible at container startup time
  • MountableFile supports classpath resources and file system paths