Skip to content

DOC-404: Document orphaned containers after Docker Compose stop #894

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
quetzalliwrites wants to merge 2 commits into
base: main
Choose a base branch
from
Open

DOC-404: Document orphaned containers after Docker Compose stop #894

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef16f22
DOC-404: Document orphaned containers after Docker Compose stop
quetzalliwrites Aug 25, 2026
ca6574b
DOC-404: Apply nik's review suggestions on the orphaned-containers FAQ
quetzalliwrites Sep 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions src/content/docs/aws/getting-started/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,30 @@ For example, a container which attempts to deploy a stack and interact with the

Refer to our [network troubleshooting guide](/aws/customization/networking/) covering several scenarios.

### Why are some containers left behind after I stop LocalStack with Docker Compose?

When LocalStack shuts down, it cleans up the auxiliary containers it started for services such as Lambda, ECS, RDS or EKS. If it is stopped before that cleanup finishes, those containers are left running.

By default, LocalStack gets only a few seconds. Docker Compose sends `SIGTERM` to the container and follows up with `SIGKILL` once `stop_grace_period` expires (10 seconds by default), and LocalStack stops waiting for its own cleanup after `SHUTDOWN_TIMEOUT` (5 seconds by default). Whichever window runs out first, LocalStack is stopped mid-cleanup and the containers survive as orphans. Cleanup that takes longer than a few seconds is the most likely to be cut short.

@purcell purcell Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
By default, LocalStack gets only a few seconds. Docker Compose sends `SIGTERM` to the container and follows up with `SIGKILL` once `stop_grace_period` expires (10 seconds by default), and LocalStack stops waiting for its own cleanup after `SHUTDOWN_TIMEOUT` (5 seconds by default). Whichever window runs out first, LocalStack is stopped mid-cleanup and the containers survive as orphans. Cleanup that takes longer than a few seconds is the most likely to be cut short.
By default, LocalStack gets only a few seconds in which to shut down. Docker Compose sends `SIGTERM` to the container and follows up with `SIGKILL` once `stop_grace_period` expires (10 seconds by default), and LocalStack stops waiting for its own cleanup after `SHUTDOWN_TIMEOUT` (5 seconds by default). Whichever window runs out first, LocalStack is stopped mid-cleanup and the containers survive as orphans. Cleanup that takes longer than a few seconds is the most likely to be cut short.


To give LocalStack enough time to shut down cleanly, raise `stop_grace_period` on the LocalStack service in your `docker-compose.yml` (for example, `3m`):

@purcell purcell Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To give LocalStack enough time to shut down cleanly, raise `stop_grace_period` on the LocalStack service in your `docker-compose.yml` (for example, `3m`):
To give LocalStack enough time to shut down cleanly, increase `stop_grace_period` on the LocalStack service in your `docker-compose.yml` (for example, `3m`):


```yaml
services:
localstack:
image: localstack/localstack-pro:latest
stop_grace_period: 3m

@purcell purcell Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
stop_grace_period: 3m
stop_grace_period: 180s

Also, writing this period as seconds makes it more obviously match the number below.

environment:
- SHUTDOWN_TIMEOUT=180
# ...
Comment thread
quetzalliwrites marked this conversation as resolved.
```

Comment thread
quetzalliwrites marked this conversation as resolved.
Raise them together. If you raise only `stop_grace_period`, LocalStack still gives up on its cleanup after 5 seconds and the container then stays up until the grace period runs out, so every docker compose stop waits the full three minutes.

@purcell purcell Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Raise them together. If you raise only `stop_grace_period`, LocalStack still gives up on its cleanup after 5 seconds and the container then stays up until the grace period runs out, so every docker compose stop waits the full three minutes.
Increase both settings. If you increase only `stop_grace_period`, LocalStack still gives up on its cleanup after 5 seconds and the container then stays up until the grace period runs out, so every `docker compose stop` waits the full three minutes.


If a previous run already left containers behind, run docker ps and remove the ones LocalStack started before starting it again.

@purcell purcell Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If a previous run already left containers behind, run docker ps and remove the ones LocalStack started before starting it again.
If a previous run already left containers behind, run `docker ps` and remove the ones LocalStack started before starting it again.


This applies to Docker Compose specifically. Starting LocalStack with `lstk` is not affected, as `lstk` waits for LocalStack to finish shutting down.

### How to resolve the pull rate limit issue for LocalStack's Docker image?

If you receive `ERROR: toomanyrequests: Too Many Requests.` when pulling the LocalStack Docker image, you have reached your pull rate limit.
Expand Down
4 changes: 4 additions & 0 deletions src/content/docs/aws/services/eks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,10 @@ K3D_START_LB_INGRESS=1
```
:::

:::note
If you run LocalStack with Docker Compose, the k3d containers backing an EKS cluster can be left behind as orphans if LocalStack is killed before it finishes shutting down. See [Why are some containers left behind after I stop LocalStack with Docker Compose?](/aws/getting-started/faq/#why-are-some-containers-left-behind-after-i-stop-localstack-with-docker-compose) for the cause and how to configure `stop_grace_period` and `SHUTDOWN_TIMEOUT` to avoid it.
:::

You can create a new cluster using the [`CreateCluster` API](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateCluster.html).

Run the following command:
Expand Down