Explain how Docker Compose support works when services are already running

[asaikali]

In my testing of the docker compose functionality with spring boot 3.1.1 I noticed a very nice behaviour that seems to be the opposite of what the docs suggest will happen.

case 1: docker compose started before the app

1. run docker-compose up and my postgres and pgAdmin start
2. run the app everything works
3. shut down the app
4. docker compose containers are still running

case 2: docker compose not running before app

1. start app, it starts docker compose up
2. run the app everything works
3. shutdown the app
4. docker compose is shutdown

The docs at https://docs.spring.io/spring-boot/docs/3.1.1/reference/htmlsingle/#features.docker-compose.lifecycle imply that the default lifecycle is for docker compose down to be run on exit. I think docs are wrong as that is not the real world behaviour I am seeing.

It might also be useful in the lifecycle section of the docs to give an explanation of the difference between docker compose start and docker compose up since those are referenced in the text. I think many folks are not familiar with the subtle difference between up and start and I had to google it to learn about the difference. I found this stack overflow answer quite handy https://stackoverflow.com/a/56624718/438319

[wilkinsona]

The docs at https://docs.spring.io/spring-boot/docs/3.1.1/reference/htmlsingle/#features.docker-compose.lifecycle imply that the default lifecycle is for docker compose down to be run on exit. I think docs are wrong as that is not the real world behaviour I am seeing.

Can you quote the text that implies that docker compose down is run on exit, @asaikali? The section in the docs that you've linked to begins "by default Spring Boot calls docker compose up when your application starts and docker compose stop when it's shut down". I can't see where the confusion with down is arising.

I think what's missing is an explanation of the behaviour differences when Docker Compose is already running (case 1 above) and when it is not (case 2 above). The docs accurately describe case 2 but do not describe case 1.

The difference is the result of this logic in DockerComposeLifecycleManager:

spring-boot/spring-boot-project/spring-boot-docker-compose/src/main/java/org/springframework/boot/docker/compose/lifecycle/DockerComposeLifecycleManager.java

Lines 121 to 128 in b8e8b1d

	if (lifecycleManagement.shouldStart() && runningServices.isEmpty()) {
	start.getCommand().applyTo(dockerCompose, start.getLogLevel());
	runningServices = dockerCompose.getRunningServices();
	wait = (wait != Wait.ONLY_IF_STARTED) ? wait : Wait.ALWAYS;
	if (lifecycleManagement.shouldStop()) {
	this.shutdownHandlers.add(() -> stop.getCommand().applyTo(dockerCompose, stop.getTimeout()));
	}
	}

Docker Compose is only started (up or start) if none of the services declaring in the compose file are already running. Similarly Docker Compose is only stopped (down or stop) if Boot started it.

[spring-projects-issues]

If you would like us to look at this issue, please provide the requested information. If the information is not provided within the next 7 days this issue will be closed.

[spring-projects-issues]

Closing due to lack of requested feedback. If you would like us to look at this issue, please provide the requested information and we will re-open the issue.

[wilkinsona]

Let's at least describe case 1 where Docker Compose is already up before the Boot app is started.