# `Testcontainers`
[🔗](https://github.com/testcontainers/testcontainers-elixir/blob/main/lib/testcontainers.ex#L1)

The main entry point into Testcontainers.

This is a GenServer that needs to be started before anything can happen.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `create_network`

Creates a Docker network.

Networks allow containers to communicate with each other using hostnames.
Use `Container.with_network/2` to attach a container to a network.

## Parameters

- `network_name`: The name of the network to create.
- `name`: The name of the Testcontainers GenServer (defaults to `Testcontainers`).

## Returns

- `{:ok, network_id}` if the network is created successfully.
- `{:ok, :already_exists}` if the network already exists.
- `{:error, reason}` on failure.

# `get_host`

Returns the host to use for connecting to the given container.

In standard mode, returns the same as `get_host/0` (the Docker host).
In container networking mode (DooD), returns the container's internal IP
since mapped ports on the bridge gateway may be unreachable.

# `get_host`

# `get_port`

Returns the port to use for connecting to the given container on the specified internal port.

In standard mode, returns the host-mapped port (same as `Container.mapped_port/2`).
In container networking mode (DooD), returns the internal port directly
since we connect to the container's IP on the bridge network.

# `get_port`

# `remove_network`

Removes a Docker network.

## Parameters

- `network_name`: The name of the network to remove.
- `name`: The name of the Testcontainers GenServer (defaults to `Testcontainers`).

## Returns

- `:ok` if the network is removed successfully.
- `{:error, reason}` on failure.

# `start`

Starts the Testcontainers application.

This will NOT terminate when the calling process exits, for ex a task.

# `start_compose`

Starts a Docker Compose environment based on the provided configuration.

## Parameters

- `config`: A `%DockerCompose{}` struct containing the configuration.

## Returns

- `{:ok, compose_env}` if the compose environment starts successfully.
- `{:error, reason}` on failure.

# `start_container`

Starts a new container based on the provided configuration, applying any specified wait strategies.

This function performs several steps:
1. Pulls the necessary Docker image.
2. Creates and starts a container with the specified configuration.
3. Registers the container with a reaper process for automatic cleanup, ensuring it is stopped and removed when the current process exits or in case of unforeseen failures.

## Parameters

- `config`: A `%Container{}` struct containing the configuration settings for the container, such as the image to use, environment variables, bound ports, and volume bindings.
## Examples

    iex> config = Testcontainers.MySqlContainer.new()
    iex> {:ok, container} = Testcontainers.start_container(config)

## Returns

- `{:ok, container}` if the container is successfully created, started, and passes all wait strategies.
- An error tuple, such as `{:error, reason}`, if there is a failure at any step in the process.

## Notes

- The container is automatically registered with a reaper process, ensuring it is stopped and removed when the current process exits, or in the case of unforeseen failures.
- It's important to specify appropriate wait strategies to ensure the container is fully ready for interaction, especially for containers that may take some time to start up services internally.

# `start_link`

Starts the Testcontainers application.

This will terminate when the calling process exits, for ex a task.

# `stop_compose`

Stops a running Docker Compose environment.

## Parameters

- `compose_env`: A `%ComposeEnvironment{}` struct representing the running environment.

## Returns

- `:ok` if the compose environment stops successfully.
- `{:error, reason}` on failure.

# `stop_container`

Stops a running container.

This sends a stop command to the specified container. The Docker daemon terminates the container process gracefully.

## Parameters

- `container_id`: The ID of the container to stop, as a string.

## Returns

- `:ok` if the container stops successfully.
- `{:error, reason}` on failure.

## Examples

    :ok = Testcontainers.Connection.stop_container("my_container_id")

---

*Consult [api-reference.md](api-reference.md) for complete listing*
