Fix stop cutting the emulator's shutdown short

[paolosalvatori]

Motivation

lstk creates the emulator container without a stop timeout, so lstk stop gets Docker's default: SIGTERM, then a kill 10 seconds later. The Azure emulator needs longer than that to remove the containers it started for Azure resources (k3d clusters, databases, storage backends), and after lstk stop they kept running. LocalStack's supervisor gives the emulator SHUTDOWN_TIMEOUT seconds to shut down (5 by default, and the Azure image is raising it to 60), but whatever that value, Docker kills the container after 10 seconds.

NOTE: if you don't want to change the way lstk stop works for all the emulators, can we at least increase the timeout for the Azure emulator to a value higher than 10 seconds (e.g. 30 seconds)?

Fixes SMF-948

Solution

• At start, lstk sets the container's Docker stop timeout to the emulator's SHUTDOWN_TIMEOUT plus 5 seconds, so the supervisor completes the shutdown, or its own kill, before Docker kills the container. lstk reads the value as the container will: the container env (a profile's env) over the image env, and a LOCALSTACK_SHUTDOWN_TIMEOUT (from the shell or a profile) in its place, as the image's entrypoint re-exports it. Without one, the supervisor's default of 5 seconds gives 10, Docker's default, so an image without the variable stops exactly as before.
• A SHUTDOWN_TIMEOUT of 0 or less tells the supervisor never to kill the emulator: lstk then gives the container a bounded 300 seconds rather than Docker's wait forever, and so it does for a container whose own stop timeout says to wait forever.
• lstk stop passes the stop timeout to Docker and waits that long plus 15 seconds, and at least 30 (the previous fixed wait). A container without a stop timeout of its own (created by an earlier lstk version or outside lstk), or with a shorter one (Podman reports its 10-second default for every container), gets the one derived from its environment the same way.

Docs

User-facing:

• lstk stop can take longer: up to the emulator's SHUTDOWN_TIMEOUT plus 5 seconds before Docker kills the container, 65 seconds with an image that sets 60.
• docker stop on a container lstk started, and the Docker daemon's own shutdown, wait as long, as the timeout is part of the container's configuration.
• A SHUTDOWN_TIMEOUT or LOCALSTACK_SHUTDOWN_TIMEOUT set in a profile's env, or a LOCALSTACK_SHUTDOWN_TIMEOUT exported in the shell, now also sets how long Docker waits for the container to stop; 0 or less means 300 seconds.

Worth a line in the lstk stop docs, and wherever SHUTDOWN_TIMEOUT is documented for lstk users.

Review

Human review advised: it changes how long lstk stop can take for every emulator image, and it was not discussed with the lstk team beforehand.

Unchanged, and now more likely to be seen: Ctrl+C during a stop prints "failed to stop LocalStack: context canceled" while Docker goes on stopping the container.

Towards SMF-948

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

Shutdown timing changes across emulator images and Docker-compatible runtimes warrant human validation.

0 open findings

What changed in this PR

Aligns Docker’s stop timeout with the emulator’s shutdown budget so cleanup can finish before Docker kills it.

Changes:

• Derives stop timeouts from environment settings and stores them at container creation.
• Extends stop waits and handles older or externally created containers.
• Adds unit and integration coverage for timeout propagation and graceful shutdown.

File	Description
test/​integration/​stop_timeout_test.go	Tests timeout configuration and graceful shutdown.
test/​integration/​main_test.go	Extracts reusable test-image creation helper.
internal/​runtime/​runtime.go	Adds timeout fields and stop parameter.
internal/​runtime/​mock_runtime.go	Updates generated stop mocks.
internal/​runtime/​external.go	Adapts unsupported stop implementation.
internal/​runtime/​external_test.go	Updates stop interface test.
internal/​runtime/​docker.go	Stores, reads, and passes Docker stop timeouts.
internal/​runtime/​docker_stop_timeout_test.go	Tests Docker API timeout handling.
internal/​container/​telemetry_test.go	Updates lifecycle test expectations.
internal/​container/​stop.go	Applies resolved timeout and wait budget.
internal/​container/​stop_timeout.go	Implements timeout derivation and bounds.
internal/​container/​stop_timeout_test.go	Tests environment precedence and fallback values.
internal/​container/​stop_test.go	Tests stop timeout selection and deadlines.
internal/​container/​start.go	Resolves timeout after image pull.
internal/​container/​start_test.go	Updates startup timeout expectations.

Files not reviewed (1)

• internal/runtime/mock_runtime.go: Generated file

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[gtsiolis]

UX LGTM. Thanks, @paolosalvatori!

Tested both binaries with real AKS and storage resources.

Binary	Result
Using lstk 1.4.1	Reported success, but emulator exited 137.
Rebuilt ./bin/lstk	Emulator exited cleanly with 0; resource containers and network removed before success

[paolosalvatori]

UX LGTM. Thanks, @paolosalvatori!

Tested both binaries with real AKS and storage resources.

Binary Result
Using lstk 1.4.1 Reported success, but emulator exited 137.
Rebuilt ./bin/lstk Emulator exited cleanly with 0; resource containers and network removed before success

Thanks for the test and review @gtsiolis 🙏