You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/modules/docker_compose.md
+26-16Lines changed: 26 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,13 +4,16 @@
4
4
5
5
Similar to generic container support, it's also possible to run a bespoke set of services specified in a `docker-compose.yml` file.
6
6
7
-
This is especially useful for projects where Docker Compose is already used in development or other environments to define services that an application may be dependent upon.
7
+
This is especially useful for projects where Docker Compose is already used in development
8
+
or other environments to define services that an application may be dependent upon.
8
9
9
-
The [`ComposeContainer`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/ComposeContainer.html) leverages [Compose V2](https://www.docker.com/blog/announcing-compose-v2-general-availability/), making it easy to use the same dependencies from the development environment within tests.
10
+
The `ComposeContainer` leverages [Compose V2](https://www.docker.com/blog/announcing-compose-v2-general-availability/),
11
+
making it easy to use the same dependencies from the development environment within tests.
10
12
11
13
## Example
12
14
13
-
A single class `ComposeContainer`, defined based on a `docker-compose.yml` file, should be sufficient to launch any number of services required by our tests:
15
+
A single class `ComposeContainer`, defined based on a `docker-compose.yml` file,
16
+
should be sufficient to launch any number of services required by our tests:
14
17
15
18
<!--codeinclude-->
16
19
[Create a ComposeContainer](../../core/src/test/java/org/testcontainers/junit/ComposeContainerTest.java) inside_block:composeContainerConstructor
@@ -28,15 +31,17 @@ services:
28
31
image: mysql:8.0.36
29
32
```
30
33
31
-
Note that it is not necessary to define ports to be exposed in the YAML file, as this would inhibit the reuse/inclusion of the file in other contexts.
34
+
Note that it is not necessary to define ports to be exposed in the YAML file,
35
+
as this would inhibit the reuse/inclusion of the file in other contexts.
32
36
33
-
Instead, Testcontainers will spin up a small 'ambassador' container, which will proxy between the Compose-managed containers and ports that are accessible to our tests. This is done using a separate, minimal container that runs socat as a TCP proxy.
37
+
Instead, Testcontainers will spin up a small 'ambassador' container,
38
+
which will proxy between the Compose-managed containers and ports that are accessible to our tests.
34
39
35
40
## ComposeContainer vs DockerComposeContainer
36
41
37
-
So far, we discussed [`ComposeContainer`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/ComposeContainer.html), which is the equivalent of docker compose [version 2](https://www.docker.com/blog/announcing-compose-v2-general-availability/).
42
+
So far, we discussed `ComposeContainer`, which is the equivalent of docker compose [version 2](https://www.docker.com/blog/announcing-compose-v2-general-availability/).
38
43
39
-
On the other hand, [`DockerComposeContainer`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/DockerComposeContainer.html) utilizes Compose V1, which has been marked deprecated by Docker.
44
+
On the other hand, `DockerComposeContainer` utilizes Compose V1, which has been marked deprecated by Docker.
40
45
41
46
The two APIs are quite similar, and most examples provided on this page can be applied to both of them.
42
47
@@ -56,10 +61,13 @@ Let's use this API to create the URL that will enable our tests to access the Re
56
61
57
62
## Wait Strategies and Startup Timeouts
58
63
Ordinarily Testcontainers will wait for up to 60 seconds for each exposed container's first mapped network port to start listening.
59
-
60
64
This simple measure provides a basic check whether a container is ready for use.
61
65
62
-
There are overloaded `withExposedService` methods that take a [`WaitStrategy`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/wait/strategy/WaitStrategy.html) where we can specify a timeout strategy per container. We can either use the fluent API to crate a custom strategy or use one of the already existing ones, accessible via the static factory methods from of the [`Wait`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/wait/strategy/Wait.html) class.
66
+
There are overloaded `withExposedService` methods that take a `WaitStrategy`
67
+
where we can specify a timeout strategy per container.
68
+
69
+
We can either use the fluent API to crate a [custom strategy](../features/startup_and_waits.md) or use one of the already existing ones,
70
+
accessible via the static factory methods from of the `Wait` class.
63
71
64
72
For instance, we can wait for exposed port and set a custom timeout:
65
73
<!--codeinclude-->
@@ -68,7 +76,8 @@ For instance, we can wait for exposed port and set a custom timeout:
68
76
69
77
Needless to say, we can define different strategies for each service in our Docker Compose setup.
70
78
71
-
For example, our Redis container can wait for a successful redis-cli command, while our db service waits for a specific log message:
79
+
For example, our Redis container can wait for a successful redis-cli command,
80
+
while our db service waits for a specific log message:
72
81
73
82
<!--codeinclude-->
74
83
[Wait for a custom command and a log message](../../core/src/test/java/org/testcontainers/junit/ComposeContainerWithWaitStrategies.java) inside_block:composeContainerWithCombinedWaitStrategies
@@ -82,7 +91,8 @@ For example, our Redis container can wait for a successful redis-cli command, wh
82
91
83
92
We can override Testcontainers' default behaviour and make it use a `docker-compose` binary installed on the local machine.
84
93
85
-
This will generally yield an experience that is closer to running _docker compose_ locally, with the caveat that Docker Compose needs to be present on dev and CI machines.
94
+
This will generally yield an experience that is closer to running _docker compose_ locally,
95
+
with the caveat that Docker Compose needs to be present on dev and CI machines.
86
96
87
97
<!--codeinclude-->
88
98
[Use ComposeContainer in 'Local Compose' mode](../../core/src/test/java/org/testcontainers/containers/ComposeProfilesOptionTest.java) inside_block:composeContainerWithLocalCompose
@@ -99,16 +109,16 @@ We can select what files should be copied only via `withCopyFilesInContainer`:
99
109
In this example, only docker compose and env files are copied over into the container that will run the Docker Compose file.
100
110
By default, all files in the same directory as the compose file are copied over.
101
111
102
-
We can use file and directory references. They are always resolved relative to the directory where the compose file resides.
103
-
104
-
This can be used with [`DockerComposeContainer`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/DockerComposeContainer.html) and [`ComposeContainer`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/ComposeContainer.html).
112
+
We can use file and directory references.
113
+
They are always resolved relative to the directory where the compose file resides.
105
114
106
115
!!! note
107
116
108
-
This can be used with [`DockerComposeContainer`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/DockerComposeContainer.html) and [`ComposeContainer`](http://static.javadoc.io/org.testcontainers/testcontainers/{{ latest_version }}/org/testcontainers/containers/ComposeContainer.html) - but **only in the containerized Compose (not with `Local Compose` mode)**.
117
+
This can be used with `DockerComposeContainer`and `ComposeContainer`, but **only in the containerized Compose (not with `Local Compose` mode)**.
109
118
110
119
## Using private repositories in Docker compose
111
-
When Docker Compose is used in container mode (not local), it's needs to be made aware of Docker settings for private repositories.
120
+
When Docker Compose is used in container mode (not local),
121
+
it needs to be made aware of Docker settings for private repositories.
112
122
By default, those setting are located in `$HOME/.docker/config.json`.
113
123
114
124
There are 3 ways to specify location of the `config.json` for Docker Compose:
0 commit comments