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 3 commits
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
19 changes: 18 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,23 @@ 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.

<Alert title="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 <code>docker compose down</code> and <code>docker compose up --wait</code>.

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
Copy Markdown

@sentry sentry bot Mar 27, 2026

Choose a reason for hiding this comment

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

Bug: The troubleshooting guide for Docker healthchecks is incomplete. It instructs creating .env.custom but omits the required --env-file flag in the docker compose command, rendering the fix ineffective.
Severity: MEDIUM

Suggested Fix

Replace the vague instruction "Then start Docker Compose." with the explicit command required to load the custom environment file, such as docker compose --env-file .env --env-file .env.custom up --wait. This ensures the HEALTHCHECK_RETRIES override is correctly applied.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: develop-docs/self-hosted/troubleshooting/docker.mdx#L34

Potential issue: The troubleshooting documentation for Docker healthchecks on slower
systems instructs users to create a `.env.custom` file with `HEALTHCHECK_RETRIES=20`.
However, it then vaguely states "Then start Docker Compose" without providing the
necessary command. Docker Compose does not automatically load `.env.custom`, so the
override will not be applied. This will cause the documented solution to fail, leaving
the user confused as the healthcheck issue persists despite following the steps. The
correct command, `docker compose --env-file .env --env-file .env.custom up --wait`, is
required to load the custom environment file.

Copy link
Copy Markdown
Member

@sergical sergical Mar 30, 2026

Choose a reason for hiding this comment

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

@arsalanyavari does this review make sense?

Copy link
Copy Markdown
Author

@arsalanyavari arsalanyavari Mar 31, 2026

Choose a reason for hiding this comment

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

@sergical I think this sentence is enough. There’s no need to explain how to start Docker Compose again, since it’s already mentioned above and in the main documentation based on @aldy505 contribution to this repo.

Copy link
Copy Markdown
Author

@arsalanyavari arsalanyavari Mar 31, 2026

Choose a reason for hiding this comment

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

If you think it’s necessary to mention this again, we can repeat that line as well (or I can move the Docker Compose start command closer to this section instead).

Copy link
Copy Markdown
Member

@sergical sergical Mar 31, 2026

Choose a reason for hiding this comment

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

i mean more so the part about creating a new .env.custom file. Can the healthcheck value not go into the existing .env file?

Copy link
Copy Markdown
Collaborator

@aldy505 aldy505 Mar 31, 2026

Choose a reason for hiding this comment

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

i mean more so the part about creating a new .env.custom file. Can the healthcheck value not go into the existing .env file?

@sergical we actually don't suggest users to update the .env file. If they want to add more changes, they should do so on .env.custom or docker-compose.override.yml, both are gitignored.

Copy link
Copy Markdown
Author

@arsalanyavari arsalanyavari Apr 2, 2026

Choose a reason for hiding this comment

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

@sergical do you think I still need to make any changes for the PR to be approved and merged, or based on @aldy505 explanation, is there nothing else I need to do?

Copy link
Copy Markdown
Member

@sergical sergical Apr 2, 2026

Choose a reason for hiding this comment

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

as long as it's clear to the user that docker compose --env-file .env --env-file .env.custom up --wait is what should be run when they have a custom env file, im good with it


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

## 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