chore(docs): 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
Title check	✅ Passed	The title accurately summarizes the main change: adding troubleshooting documentation for Graphile Worker to the docs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

---

🧹 Recent nitpick comments

docs/self-hosting/docker.mdx (1)

333-334: Consider breaking this into a more scannable format.

The troubleshooting content is accurate and helpful, but this single paragraph is dense compared to other troubleshooting bullets in this section. Consider reformatting for better readability:

📝 Suggested formatting improvement

-- **Deploy fails with `ERROR: schema "graphile_worker" does not exist`.** This error occurs when Graphile Worker migrations fail to run during webapp startup. Check the webapp logs for certificate-related errors like `self-signed certificate in certificate chain`. This is often caused by PostgreSQL SSL certificate issues when using an external PostgreSQL instance with SSL enabled. Ensure that both the webapp and supervisor containers have access to the same CA certificate used by your PostgreSQL instance. You can configure this by mounting the certificate file and setting the `NODE_EXTRA_CA_CERTS` environment variable to point to the certificate path. Once the certificate issue is resolved, the migrations will complete and create the required `graphile_worker` schema.
+- **Deploy fails with `ERROR: schema "graphile_worker" does not exist`.** This error occurs when Graphile Worker migrations fail to run during webapp startup.
+
+  Check the webapp logs for certificate-related errors like `self-signed certificate in certificate chain`. This is often caused by PostgreSQL SSL certificate issues when using an external PostgreSQL instance with SSL enabled.
+
+  To resolve:
+  1. Ensure both webapp and supervisor containers have access to the same CA certificate used by your PostgreSQL instance
+  2. Mount the certificate file and set the `NODE_EXTRA_CA_CERTS` environment variable to point to the certificate path
+
+  Once the certificate issue is resolved, the migrations will complete and create the required `graphile_worker` schema.

docs/self-hosting/kubernetes.mdx (1)

558-558: Consider also referencing the local Kubernetes SSL configuration section.

The cross-reference to Docker troubleshooting is helpful, but Kubernetes users already have a detailed SSL configuration example in this same file at the PostgreSQL SSL with custom CA certificates section (lines 314-356). Consider referencing both for a more complete experience:

📝 Suggested improvement

-- **Deploy fails with `ERROR: schema "graphile_worker" does not exist`**: See the [Docker troubleshooting](/self-hosting/docker#troubleshooting) section for details on resolving PostgreSQL SSL certificate issues that prevent Graphile Worker migrations.
+- **Deploy fails with `ERROR: schema "graphile_worker" does not exist`**: This is typically caused by PostgreSQL SSL certificate issues. See [PostgreSQL SSL with custom CA certificates](`#postgresql-ssl-with-custom-ca-certificates`) above for configuration examples, or the [Docker troubleshooting](/self-hosting/docker#troubleshooting) section for diagnostic steps.

---

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 260fb7c and a65dbcc.

📒 Files selected for processing (2)

• docs/self-hosting/docker.mdx
• docs/self-hosting/kubernetes.mdx

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: claude-review
• GitHub Check: Analyze (javascript-typescript)

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

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.