docs(self-hosted): Update troubleshooting Docker healthcheck (clarify unhealthy container troubleshooting on slower systems)#17149
Conversation
|
@arsalanyavari is attempting to deploy a commit to the Sentry Team on Vercel. A member of the Team first needs to authorize it. |
There was a problem hiding this comment.
Pull request overview
Updates the self-hosted Docker troubleshooting documentation to help users resolve container for service "${servicename}" is unhealthy on slower systems by explaining how to tune Docker healthcheck settings via environment overrides.
Changes:
- Updates the “Container Healthcheck” section to direct users toward overriding
HEALTHCHECK_*values via.env.custom. - Adds a note for slower/minimum-spec systems, including an example of increasing
HEALTHCHECK_RETRIES.
| > [!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`. | ||
| > |
There was a problem hiding this comment.
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).
| > Then start Docker Compose. | ||
| > |
There was a problem hiding this comment.
“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.
| > 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 | |
| > ``` | |
| > |
…ra white space. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
| HEALTHCHECK_RETRIES=20 | ||
| ``` | ||
|
|
||
| Then start Docker Compose. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
i mean more so the part about creating a new .env.custom file. Can the healthcheck value not go into the existing .env file?
There was a problem hiding this comment.
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.
aldy505
changed the title
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
coolguyzone
left a comment
coolguyzone
left a comment
There was a problem hiding this comment.
LGTM, please resolve the sentrybot feedback that Serge commented on as well.
DESCRIBE YOUR PR
This PR updates the self-hosted Docker troubleshooting docs with guidance for resolving
container for service "${servicename}" is unhealthyon slower systems.It adds a note explaining how to override
HEALTHCHECK_*values from.envin.env.custom, with an example usingHEALTHCHECK_RETRIESthat could resolve the problem.Closes getsentry/self-hosted#4231
IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
LEGAL BOILERPLATE
Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.
EXTRA RESOURCES