docs(self-hosting): added graphile worker troubleshooting to docs

[isshaddad]

Add troubleshooting documentation for graphile worker schema migration failures and PostgreSQL SSL certificate issues that prevent worker initialization.

[changeset-bot]

⚠️ No Changeset found

Latest commit: a65dbcc

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Walkthrough

This pull request adds troubleshooting documentation to the Docker and Kubernetes self-hosting guides. Both changes describe a deployment failure where the graphile_worker schema does not exist during migrations. The documentation attributes this to PostgreSQL SSL certificate issues when using external databases and provides remediation steps: verifying CA certificate access across containers, mounting certificates appropriately, and setting the NODE_EXTRA_CA_CERTS environment variable. The Kubernetes documentation references the Docker guide for detailed resolution steps.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is minimal and lacks required sections from the template including testing steps, changelog, and checklist items.	Fill out all template sections including the checklist, testing steps, changelog details, and issue reference to meet repository standards.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately describes the main change: adding Graphile Worker troubleshooting documentation to the self-hosting guides. It is concise, specific, and clearly relates to the changeset which adds troubleshooting notes to both Docker and Kubernetes documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/add-graphile-worker-troubleshooting

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

PR Review: chore(docs): added graphile worker troubleshooting to docs

Thanks for contributing this documentation improvement! Adding troubleshooting guidance for real-world issues users encounter when self-hosting is very valuable.

Overall Assessment

This is a helpful addition that documents a specific error scenario with actionable steps to resolve it. The changes are focused and appropriate for a documentation PR.

Suggestions for Improvement

1. Long paragraph in docker.mdx (line 333)

The troubleshooting entry in docker.mdx is quite long as a single paragraph. Consider breaking it into a more structured format for better readability - separating the diagnosis, cause, and solution into distinct sections with numbered steps.

2. Consider adding a code example

Since the fix involves mounting certificates and setting environment variables, a brief docker-compose.yml example showing how to mount the certificate and set NODE_EXTRA_CA_CERTS would be helpful for users.

3. Minor: Consider anchor link accuracy

The kubernetes.mdx references /self-hosting/docker#troubleshooting which should work correctly, but you may want to verify the anchor is generated as expected with your docs framework.

What looks good

• The error message is quoted exactly as users would see it, making it easy to find via search
• The explanation correctly identifies the root cause (SSL certificate issues with external PostgreSQL)
• The Kubernetes entry appropriately cross-references the Docker docs to avoid duplication
• The fix involving NODE_EXTRA_CA_CERTS is the correct Node.js approach for custom CA certificates

Minor nit

The phrase both the webapp and supervisor containers is good, but if this is primarily a webapp startup issue (since thats where graphile_worker runs), you might want to clarify that the webapp is the critical one, while supervisor may also need it for its own database connections.

---

Verdict: This is a solid documentation improvement. The suggestions above are optional enhancements for readability. The current content is accurate and will help users resolve this issue.

Approving as-is, with optional suggestions for the author to consider.

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.