Configuration

This page documents all configuration options for Testcontainers OCaml.

Environment Variables

Docker Connection

Test Configuration

CI Detection

Default Values

Container Request Defaults

(* Default values when creating a container request *)
let defaults = {
  exposed_ports = [];
  environment = [];
  labels = [];
  command = None;
  entrypoint = None;
  working_dir = None;
  user = None;
  privileged = false;
  mounts = [];
  wait_strategy = None;
  startup_timeout = 60.0;
  auto_remove = false;
  name = None;
}

Wait Strategy Defaults

(* Default timeout for wait strategies *)
let default_timeout = 60.0  (* seconds *)

(* Default poll interval *)
let default_poll_interval = 0.1  (* seconds, 100ms *)

Module Defaults

PostgreSQL

let defaults = {
  image = "postgres:16-alpine";
  database = "test";
  username = "test";
  password = "test";
  port = 5432;
}

MySQL

let defaults = {
  image = "mysql:8";
  database = "test";
  username = "test";
  password = "test";
  root_password = "root";
  port = 3306;
}

MongoDB

let defaults = {
  image = "mongo:7";
  username = None;  (* No auth by default *)
  password = None;
  port = 27017;
}

Redis

let defaults = {
  image = "redis:7-alpine";
  port = 6379;
}

RabbitMQ

let defaults = {
  image = "rabbitmq:3-management-alpine";
  username = "guest";
  password = "guest";
  vhost = "/";
  amqp_port = 5672;
  management_port = 15672;
}

Timeouts

Startup Timeout

Maximum time to wait for a container to be ready:

Container_request.with_startup_timeout 120.0  (* 2 minutes *)

Wait Strategy Timeout

Maximum time for a wait strategy to succeed:

Wait_strategy.with_timeout 30.0  (* 30 seconds *)

Poll Interval

How often to check wait conditions:

Wait_strategy.with_poll_interval 0.5  (* 500ms *)

Stop Timeout

How long to wait for graceful shutdown:

Container.stop ~timeout:10.0 container  (* 10 seconds *)

Docker API

API Version

let api_version = "v1.43"

Socket Path

let docker_socket = "/var/run/docker.sock"

Programmatic Configuration

Reading Environment

let get_timeout () =
  match Sys.getenv_opt "CONTAINER_TIMEOUT" with
  | Some t -> (try float_of_string t with _ -> 60.0)
  | None -> 60.0

let skip_integration () =
  match Sys.getenv_opt "SKIP_INTEGRATION_TESTS" with
  | Some "1" | Some "true" -> true
  | _ -> false

let is_ci () =
  Sys.getenv_opt "CI" = Some "true"

Dynamic Configuration

let create_request () =
  let timeout = get_timeout () in
  let image =
    match Sys.getenv_opt "POSTGRES_IMAGE" with
    | Some img -> img
    | None -> "postgres:16-alpine"
  in
  Container_request.create image
  |> Container_request.with_startup_timeout timeout

Common Configuration Patterns

Development vs CI

let config =
  if is_ci () then
    (* CI: longer timeouts, specific images *)
    Container_request.create "postgres:16-alpine"
    |> Container_request.with_startup_timeout 120.0
  else
    (* Dev: faster startup, latest images okay *)
    Container_request.create "postgres:16"
    |> Container_request.with_startup_timeout 60.0

Configurable Test Suites

let integration_tests =
  if skip_integration () then [] else [
    test_database;
    test_cache;
    test_queue;
  ]

Image Override

let postgres_image =
  Sys.getenv_opt "TEST_POSTGRES_IMAGE"
  |> Option.value ~default:"postgres:16-alpine"

let config =
  Postgres_container.create ()
  |> Postgres_container.with_image postgres_image

Docker Desktop Settings

macOS / Windows

Docker Desktop exposes the socket at the default location. No configuration needed.

Resource Limits

Configure in Docker Desktop preferences:

• Memory: Recommend at least 4GB for integration tests
• CPUs: 2+ recommended
• Disk: Ensure adequate space for images

WSL2 (Windows)

# In WSL2, Docker socket is available at default location
export DOCKER_HOST=unix:///var/run/docker.sock

Troubleshooting Configuration

Verify Docker Connection

let check_docker () =
  Lwt_main.run (
    let* ok = Docker_client.ping () in
    if ok then
      print_endline "Docker connection OK"
    else
      print_endline "Docker connection failed";
    Lwt.return_unit
  )

Check Environment

let print_config () =
  Printf.printf "DOCKER_HOST: %s\n"
    (Sys.getenv_opt "DOCKER_HOST" |> Option.value ~default:"(default)");
  Printf.printf "CI: %s\n"
    (Sys.getenv_opt "CI" |> Option.value ~default:"false");
  Printf.printf "Skip integration: %b\n" (skip_integration ())

Debug Mode

let debug = Sys.getenv_opt "DEBUG" = Some "true"

let log msg =
  if debug then Printf.printf "[DEBUG] %s\n" msg

let start_with_debug request =
  log "Starting container...";
  let* container = Container.start request in
  log (Printf.sprintf "Container started: %s" (Container.id container));
  Lwt.return container