Update the docker deployment guide documentation - #4277
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
🚧 Files skipped from review as they are similar to previous changes (4)
📝 WalkthroughWalkthroughDocker deployment documentation now uses corrected container paths, a Docker-ready configuration example, the liveness health endpoint, numeric PostgreSQL ports, persistent certificate and secret volumes, and a pinned local PostgreSQL image. ChangesDocker deployment documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 Checkov (3.3.8)install/local-development/docker-compose.ymlTraceback (most recent call last): 🔧 ESLint
docs/content/deployment/deployment-paths/docker-production.mdxESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox. docs/content/deployment/deployment-paths/docker.mdxESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox. docs/content/deployment/production-guidelines.mdxESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox. 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. Comment |
There was a problem hiding this comment.
Pull request overview
This PR corrects multiple inaccuracies in the Docker deployment documentation for ThunderID so that the documented commands and mounts match the actual container filesystem and runtime requirements, plus it stabilizes local dev PostgreSQL by pinning a compatible image tag.
Changes:
- Fixes Docker/Compose mount paths and health check endpoints to match the container layout and available routes.
- Replaces/updates configuration guidance to include a Docker-ready
deployment.yamlexample (bind address +server.public_url) and removes a non-working Compose section from the Docker guide. - Pins local-development PostgreSQL to
postgres:16-alpineto avoid data-directory incompatibilities with newer major versions.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| install/local-development/docker-compose.yml | Pins PostgreSQL image tag for stable local dev volume layout. |
| docs/content/deployment/production-guidelines.mdx | Fixes Postgres port type and updates Docker TLS/certs mounting guidance. |
| docs/content/deployment/deployment-paths/docker.mdx | Updates Docker guide: removes non-working Compose section and provides Docker-ready config example. |
| docs/content/deployment/deployment-paths/docker-production.mdx | Corrects production Docker recommendations: mounts, pinned image example, and healthcheck endpoint. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/content/deployment/deployment-paths/docker-production.mdx (1)
1-1: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winStale
:latesttags contradict this PR's own pinning guidance.docker-production.mdxadds a "Pin the Image Version" section instructing readers to always use an explicit release tag instead oflatest, but two examples elsewhere in the same doc set still hardcode:latest, undermining that guidance.
docs/content/deployment/deployment-paths/docker-production.mdx#L61-66: replaceghcr.io/thunder-id/thunderid:latestin the "Persist Data with Named Volumes" example with the same<version>placeholder used in the pinning section.docs/content/deployment/production-guidelines.mdx#L134-146: replaceghcr.io/thunder-id/thunderid:latestin the cert-replacementdocker runexample with a pinned/placeholder version.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/content/deployment/deployment-paths/docker-production.mdx` at line 1, Replace the hardcoded :latest image tags in the “Persist Data with Named Volumes” example and the cert-replacement docker run example with the established <version> placeholder, keeping both examples consistent with the “Pin the Image Version” guidance.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/deployment/deployment-paths/docker-production.mdx`:
- Around line 61-66: Update the Docker run example in the deployment
documentation to use a pinned ThunderID image version instead of the :latest
tag. Keep the command structure unchanged and align the image reference with the
version-pinning guidance and the corresponding production-guidelines example.
- Around line 68-71: Reconcile the security-directory example under “Persist
Data with Named Volumes” with the documented `thunderid-certs` named-volume
workflow: replace the host bind mount in the deployment instructions with the
established named-volume usage, or explicitly explain the intentional deviation
and its implications. Keep the TLS certificate and encryption-key persistence
guidance consistent with the related Docker documentation.
In `@docs/content/deployment/deployment-paths/docker.mdx`:
- Around line 154-163: The Docker-ready SMTP configuration must not use
127.0.0.1 as the default host. Update the smtp.host example to a
container-reachable value such as host.docker.internal and document the required
Linux --add-host option, or clearly mark the host as a user-replaceable
placeholder consistent with the other deployment credentials.
In `@docs/content/deployment/production-guidelines.mdx`:
- Around line 134-146: Update the Docker image reference in the production
deployment example to use the documented pinned release or version variable
instead of the mutable `:latest` tag, matching the convention used in
`docker-production.mdx` and the consolidated guidance. Preserve the existing
volume mounts and container paths.
---
Outside diff comments:
In `@docs/content/deployment/deployment-paths/docker-production.mdx`:
- Line 1: Replace the hardcoded :latest image tags in the “Persist Data with
Named Volumes” example and the cert-replacement docker run example with the
established <version> placeholder, keeping both examples consistent with the
“Pin the Image Version” guidance.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 006c0703-8d20-4d9f-bec0-f64ab5b3b296
📒 Files selected for processing (4)
docs/content/deployment/deployment-paths/docker-production.mdxdocs/content/deployment/deployment-paths/docker.mdxdocs/content/deployment/production-guidelines.mdxinstall/local-development/docker-compose.yml
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Purpose
The Docker deployment guides contained several errors that caused documented commands to fail silently or produce a non-working deployment. All fixes were reproduced against
ghcr.io/thunder-id/thunderid:latest.Fixes #4228
Affected files:
docs/content/deployment/deployment-paths/docker.mdxdocs/content/deployment/deployment-paths/docker-production.mdxdocs/content/deployment/production-guidelines.mdxinstall/local-development/docker-compose.ymlApproach
Fixed the following issues:
Incorrect container paths. Several
docker run/ Compose examples mounted into/opt/thunder/..., but the container's application directory is/opt/thunderid. Corrected the data volume, security-directory, anddeployment.yamlmounts indocker-production.mdx, and the TLS command mounts (deployment.yaml,server.cert,server.key) inproduction-guidelines.mdx.Security directory mounted to the wrong subpath.
docker-production.mdxmounted toconfig/resources/security, but setup writes the TLS, JWT, and encryption keys toconfig/certs. Corrected the target to/opt/thunderid/config/certs.Identical "Avoid" and "Prefer" image-pin examples. In "Pin the Image Version", both examples showed
:latest. The "Prefer" example now shows a pinned tag (ghcr.io/thunder-id/thunderid:<version>).Health check hit a non-existent endpoint. The Compose health check used
/healthThe server registers/health/livenessand/health/readiness. Updated to/health/liveness.Customize section pointed to a config that cannot work in Docker. The "Customize the Configuration" section pointed readers to the default
deployment.yaml(hostname: "localhost", nopublic_url), which the image only works with because the Dockerfile patches those values at build time. A mounted file bypasses that patch. Replaced the pointer with a Docker-ready inline configuration (hostname: "0.0.0.0"and apublic_url).PostgreSQL
portquoted as a string. The Postgres blocks inproduction-guidelines.mdxusedport: "5432"(string); the schema expects an integer.Removed the "Run with Docker Compose" section from
docker.mdx, since its example could not produce a working PostgreSQL deployment as written.Pinned the PostgreSQL version in
install/local-development/docker-compose.yml. The volume is mounted atpostgres_data:/var/lib/postgresql/data, but PostgreSQL 18 and later changed the data directory, so the untaggedpostgresimage crash-loops. Pinned topostgres:16-alpineto keep the data directory consistent with the mount.Related Issues
Related PRs
Checklist
breaking changelabel added.Security checks
Summary by CodeRabbit
Summary by CodeRabbit
Documentation
deployment.yamlexample, simplified access instructions, and clarified requirements for external PostgreSQL./opt/thunderid/...layout.Chores
16-alpinefor consistent setup.