Skip to content

docs(self-hosted): Update troubleshooting Docker healthcheck (clarify unhealthy container troubleshooting on slower systems) #17149

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
arsalanyavari wants to merge 5 commits into
base: master
Choose a base branch
from
+18 −1
Open

docs(self-hosted): Update troubleshooting Docker healthcheck (clarify unhealthy container troubleshooting on slower systems) #17149

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
798c5fa
Update troubleshooting Docker healthcheck
arsalanyavari Mar 27, 2026
6a09912
Update develop-docs/self-hosted/troubleshooting/docker.mdx remove ext…
arsalanyavari Mar 27, 2026
47a4f58
Revise Docker troubleshooting notes for healthchecks
arsalanyavari Mar 27, 2026
4dfc3e2
Fix formatting in troubleshooting Docker documentation
arsalanyavari Mar 27, 2026
63fddcd
Update docker.mdx
aldy505 Mar 27, 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
18 changes: 17 additions & 1 deletion develop-docs/self-hosted/troubleshooting/docker.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Around version 25.1.0 to 25.4.0, users which did not have `docker compose` plugi

## Container Healthcheck

There may be some circumstances which you may want to increase or decrease healthcheck interval, timeout or retries for your custom needs. This can be achieved by editing `HEALTHCHECK_INTERVAL`, `HEALTHCHECK_TIMEOUT`, `HEALTHCHECK_RETRIES` variables' values in `.env`.
There may be some circumstances which you may want to increase or decrease healthcheck interval, timeout or retries for your custom needs. This can be achieved by overriding the values of `HEALTHCHECK_INTERVAL`, `HEALTHCHECK_TIMEOUT` and `HEALTHCHECK_RETRIES` defined in `.env` in `.env.custom`.

Occasionally, you might see an error like this
```
Expand All @@ -19,6 +19,22 @@ container for service "${servicename}" is unhealthy

This can usually be resolved by running `docker compose down` and `docker compose up --wait` or rerunning the install script.

> [!NOTE]
> On slower systems, including systems that only meet the minimum resource requirements for self-hosted Sentry, this issue may still persist even after rerunning `docker compose down` and `docker compose up --wait`.
>
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

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

This uses GitHub-style callouts (> [!NOTE]), but elsewhere in these docs the convention is to use the MDX <Alert ...> component for notes/tips/warnings. Using a different admonition format here may not render as intended on the docs site; consider converting this block to <Alert level="info" title="Note">…</Alert> (or the appropriate level/title) to match existing self-hosted docs (e.g. develop-docs/self-hosted/troubleshooting/kafka.mdx).

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Author

@arsalanyavari arsalanyavari Mar 27, 2026

Choose a reason for hiding this comment

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

I fix it based on another file in doc

> In this case, you can override the healthcheck parameters defined in `.env` by setting custom values in `.env.custom`.
>
> For example, increasing `HEALTHCHECK_RETRIES` may resolve the issue:
>
> ```shell
> # .env.custom
> HEALTHCHECK_RETRIES=20
> ```
>
> Then start Docker Compose.
>
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

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

“Then start Docker Compose.” is ambiguous, especially since .env.custom won’t take effect unless the user runs Compose with the right --env-file flags. Consider making this step explicit (for example, calling out docker compose --env-file .env --env-file .env.custom up --wait, or pointing readers to the configuration docs) so readers don’t edit .env.custom and then rerun the same command with no change.

Suggested change
> Then start Docker Compose.
>
> Then restart Docker Compose so it picks up the new settings:
>
> ```shell
> docker compose --env-file .env --env-file .env.custom up --wait
> ```
>

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Author

@arsalanyavari arsalanyavari Mar 27, 2026

Choose a reason for hiding this comment

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

this one is fixed also.

> Depending on your system, you may also need to adjust other `HEALTHCHECK_*` values.

## Docker Network Conflicting IP Address

Self-hosted Sentry is using Docker's bridge networking, in which use a specific private IP range. By default, Docker uses `172.17.0.0/16` range (`172.17.0.0`-`172.17.255.255`). This may cause conflict with your private network. You can change Docker's default IP range by configuring the `/etc/docker/daemon.json` file. If the file does not exists, you can create it yourself.
Expand Down
Loading