docs: add troubleshooting section for Docker build and runtime issues#951
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a Docker troubleshooting runbook to help developers debug local builds vs published GHCR images, and links to it from the deployment docs.
Changes:
- Add a new
docs/docker-debugging.mdrunbook with step-by-step commands for building/running locally and comparing with GHCR. - Add a “Troubleshooting Docker Build and Runtime Issues” section to
docs/deploy.mdlinking to the new runbook.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/docker-debugging.md | New debugging runbook covering local build/run, GHCR pull/run, and common failure patterns. |
| docs/deploy.md | Adds a troubleshooting pointer to the new Docker debugging runbook. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --env-file ./.env \ | ||
| --env NODE_ENV=development \ | ||
| --env HOST=0.0.0.0 \ | ||
| -p 3000:3000 \ | ||
| -it safe-settings:local |
There was a problem hiding this comment.
The command examples use tab characters for indentation (e.g., the --env-file / --env / -p lines). This repo’s .editorconfig specifies indent_style = space, and tabs often paste inconsistently across shells/editors. Replace the leading tabs with spaces throughout the code blocks to keep formatting consistent and copy/paste-friendly.
| --env-file ./.env \ | |
| --env NODE_ENV=development \ | |
| --env HOST=0.0.0.0 \ | |
| -p 3000:3000 \ | |
| -it safe-settings:local | |
| --env-file ./.env \ | |
| --env NODE_ENV=development \ | |
| --env HOST=0.0.0.0 \ | |
| -p 3000:3000 \ | |
| -it safe-settings:local |
| ```bash | ||
| docker pull ghcr.io/github/safe-settings:2.1.19 | ||
| ``` |
There was a problem hiding this comment.
The GHCR image tag is hard-coded to 2.1.19 in multiple commands. Other docs in this repo reference different tags (e.g., deploy.md mentions 2.1.13, awslambda.md mentions 2.1.17), so this is likely to become stale/confusing. Consider using a placeholder (e.g., $SAFE_SETTINGS_TAG) and/or pointing readers to where to find the current recommended tag, then reuse that consistently across docs.
No description provided.