docs(cloudron): add SSH diagnostics, forum reference, and database troubleshooting#8
Conversation
…oubleshooting Add comprehensive troubleshooting guidance based on real-world Vaultwarden debugging session: - SSH diagnostic access commands (docker ps, logs, inspect, exec) - Container state diagnosis table (Up, Restarting, Exited, Created) - Database troubleshooting for MySQL (credentials, charset/collation fixes) - App recovery mode usage instructions - Post-update failure troubleshooting workflow - Cloudron forum as primary resource for known issues - Cross-references to vaultwarden.md and wordpress subagents - Quick reference additions for SSH, Docker, and DB credentials
WalkthroughThis change enhances the Cloudron hosting documentation with comprehensive troubleshooting and operational guidance. Quick-reference materials, diagnostic procedures, container state mapping, database troubleshooting workflows, and app recovery instructions have been added to support operators managing Cloudron deployments. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Pre-merge checks✅ Passed checks (3 passed)
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 |
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly expands the Cloudron troubleshooting documentation by incorporating practical, step-by-step guides for common issues. It covers essential diagnostic techniques like SSH access, Docker container inspection, and detailed MySQL database troubleshooting, including specific fixes for charset/collation problems. The update also integrates the Cloudron forum as a key resource and provides a structured workflow for resolving app startup failures after updates, aiming to empower users with more self-service diagnostic capabilities. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Tue Jan 6 15:52:18 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly enhances the Cloudron troubleshooting documentation by adding comprehensive guidance based on real-world debugging scenarios. The new sections covering SSH diagnostics, container inspection, and database troubleshooting are well-structured and provide immense value. The inclusion of common failure patterns and cross-references is also excellent. I have a few minor suggestions to improve the clarity and robustness of the provided shell commands.
| - **User mgmt**: `users`, `add-user`, `update-user`, `reset-password` | ||
| - **SSH access**: `ssh root@cloudron.domain.com` for direct server diagnosis | ||
| - **Forum**: [forum.cloudron.io](https://forum.cloudron.io) for known issues and solutions | ||
| - **Docker**: `docker ps -a` (states), `docker logs <container>`, `docker exec -it mysql mysql` |
There was a problem hiding this comment.
The docker exec -it mysql mysql command in the quick reference is likely to fail without credentials and can be misleading. It's better to provide a more generally useful command for container access, like docker exec -it <container> /bin/bash, and leave the specific database connection details to the dedicated troubleshooting section below where it is explained in detail. Please re-add the backticks for code formatting when applying the suggestion.
| - **Docker**: `docker ps -a` (states), `docker logs <container>`, `docker exec -it mysql mysql` | |
| - **Docker**: docker ps -a (states), docker logs <container>, docker exec -it <container> /bin/bash |
| docker exec -it mysql mysql -u<username> -p<password> <database> | ||
|
|
||
| # Or use root access | ||
| docker exec -it mysql mysql -uroot -p$(cat /home/yellowtent/platformdata/mysql/root_password) |
There was a problem hiding this comment.
It's a good practice to wrap the command substitution $(...) in double quotes. This prevents word splitting and filename expansion, making the command more robust, especially if the password contains whitespace or other special characters.
| docker exec -it mysql mysql -uroot -p$(cat /home/yellowtent/platformdata/mysql/root_password) | |
| docker exec -it mysql mysql -uroot -p"$(cat /home/yellowtent/platformdata/mysql/root_password)" |
|
|
||
| When apps fail after updates (common pattern): | ||
|
|
||
| 1. **Check container state**: `docker ps -a | grep <app>` |
There was a problem hiding this comment.
The placeholder <app> is a bit ambiguous. To improve clarity for the user, consider specifying what it refers to. Since Cloudron containers are often named after the app's subdomain, using <app_subdomain> would be more explicit. Please re-add the backticks for code formatting when applying the suggestion.
| 1. **Check container state**: `docker ps -a | grep <app>` | |
| 1. **Check container state**: docker ps -a | grep <app_subdomain> |
🤖 Augment PR SummarySummary: Expands the Cloudron subagent documentation with practical troubleshooting guidance inspired by a real-world post-update Vaultwarden outage. Changes:
Technical Notes: The guide includes direct 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| - **SSH access**: `ssh root@cloudron.domain.com` for direct server diagnosis | ||
| - **Forum**: [forum.cloudron.io](https://forum.cloudron.io) for known issues and solutions | ||
| - **Docker**: `docker ps -a` (states), `docker logs <container>`, `docker exec -it mysql mysql` | ||
| - **DB creds**: `docker inspect <container> | grep CLOUDRON_MYSQL` |
There was a problem hiding this comment.
docker inspect <container> | grep CLOUDRON_MYSQL will surface DB credentials; it may be worth adding a short reminder to redact secrets before pasting output into forum posts or tickets.
🤖 Was this useful? React with 👍 or 👎
| docker exec -it mysql mysql -u<username> -p<password> <database> | ||
|
|
||
| # Or use root access | ||
| docker exec -it mysql mysql -uroot -p$(cat /home/yellowtent/platformdata/mysql/root_password) |
There was a problem hiding this comment.
Minor security footnote: passing the password via -p$(cat ...) can expose it in the process list while the command runs, so a brief caution here could help prevent accidental credential leakage.
🤖 Was this useful? React with 👍 or 👎
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI Agents
In @.agent/services/hosting/cloudron.md:
- Around line 367-372: The two subagent links in the App-Specific
Troubleshooting section are incorrect; update the Vaultwarden link
`tools/credentials/vaultwarden.md` to the relative path
`../../tools/credentials/vaultwarden.md` and update the WordPress link
`tools/wordpress/` to `../../tools/wordpress` so they correctly point to
`.agent/tools/credentials/vaultwarden.md` and `.agent/tools/wordpress` from the
`cloudron.md` file; modify the entries under "App-Specific Troubleshooting" (the
Vaultwarden and WordPress bullet lines) accordingly.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
.agent/services/hosting/cloudron.md
🧰 Additional context used
🧠 Learnings (4)
📚 Learning: 2025-11-29T04:34:27.158Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-29T04:34:27.158Z
Learning: All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truth
Applied to files:
.agent/services/hosting/cloudron.md
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Reference AGENTS.md (authoritative) instead of AGENT.md for AI assistant guidance
Applied to files:
.agent/services/hosting/cloudron.md
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Maintain all AI assistant instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Applied to files:
.agent/services/hosting/cloudron.md
📚 Learning: 2025-11-29T04:34:30.742Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Maintain all instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Applied to files:
.agent/services/hosting/cloudron.md
🪛 LanguageTool
.agent/services/hosting/cloudron.md
[style] ~217-~217: Consider a different adjective to strengthen your wording.
Context: ...ons ### SSH Diagnostic Access For deep troubleshooting, SSH directly into the ...
(DEEP_PROFOUND)
[uncategorized] ~372-~372: The official name of this content management system is spelled with a capital “P”.
Context: ...anager troubleshooting - WordPress: tools/wordpress/ - WordPress-specific issues ## 📊 **...
(WORDPRESS)
⏰ 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). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (8)
.agent/services/hosting/cloudron.md (8)
28-31: Quick reference enhancements look solid.The SSH access, forum link, Docker commands, and database credentials pattern are practical and directly address operational needs. These fit well into the quick-reference section for operators who need immediate diagnostic guidance.
206-213: Forum guidance is well-positioned and practical.The troubleshooting resources section clearly directs operators to search known issues, check app-specific categories, and look for Cloudron staff solutions. This reflects the real incident pattern where forum had the solution.
215-240: SSH diagnostic commands are comprehensive and accurate.The Docker commands cover essential diagnostic patterns: state inspection, log viewing (including real-time), environment inspection, and interactive container access. Operators will find these immediately actionable for troubleshooting.
242-250: Container state diagnosis table is clear and actionable.The state mapping from
docker psoutput to diagnosis and recommended action is accurate and will help operators quickly identify problem patterns (especially the "Restarting" crash-loop scenario that likely appeared in the real incident).
251-271: Database troubleshooting approach is sound, verify Cloudron-specific paths.The credential extraction pattern (docker inspect | grep CLOUDRON_MYSQL) and connection methods are technically correct. However, verify that the root password path
/home/yellowtent/platformdata/mysql/root_passwordis accurate for your Cloudron deployment—this path may vary by version or installation.Confirm the following Cloudron-specific details match your deployment:
- Env var prefix:
CLOUDRON_MYSQL_*- Root password file path:
/home/yellowtent/platformdata/mysql/root_password- MySQL container name:
mysqlIf these differ, update the documentation to reflect your actual environment.
273-296: Database fix examples are grounded in the real incident and well-documented.The charset/collation conversion examples directly reflect the Vaultwarden post-update issue mentioned in PR objectives. The SQL syntax is correct, utf8mb4 is the right target charset, and including schema inspection queries helps operators verify before/after states. The migration error notes appropriately point back to the forum for app-specific issues.
298-351: App recovery and startup failure workflows are methodical and incident-informed.The 7-step troubleshooting sequence (check state → logs → forum → database → recovery mode → apply fix → restart) reflects the actual incident resolution process. Providing both dashboard and docker-exec approaches for recovery mode gives operators flexibility based on access level.
1-12: Verify documentation architecture aligns with AGENTS.md centralization.Per retrieved learnings, operational guidance should be maintained in
AGENTS.mdas the single source of truth. Confirm whether this Cloudron subagent documentation should remain in.agent/services/hosting/cloudron.mdor be consolidated/referenced fromAGENTS.md. This is an architectural question rather than a content quality issue—the documentation itself is excellent.
| ### **App-Specific Troubleshooting** | ||
|
|
||
| For app-specific issues, check these subagents: | ||
|
|
||
| - **Vaultwarden**: `tools/credentials/vaultwarden.md` - Password manager troubleshooting | ||
| - **WordPress**: `tools/wordpress/` - WordPress-specific issues |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify that referenced subagent documentation paths exist
echo "Checking vaultwarden reference..."
if [ -f "tools/credentials/vaultwarden.md" ]; then
echo "✓ Found: tools/credentials/vaultwarden.md"
else
echo "✗ NOT FOUND: tools/credentials/vaultwarden.md"
echo " Searching for vaultwarden.md..."
find . -name "vaultwarden.md" -type f 2>/dev/null | head -5
fi
echo -e "\nChecking wordpress reference..."
if [ -d "tools/wordpress" ]; then
echo "✓ Found: tools/wordpress/"
else
echo "✗ NOT FOUND: tools/wordpress/"
echo " Searching for wordpress directories..."
find . -type d -name "*wordpress*" 2>/dev/null | head -5
fi
echo -e "\nListing directory structure of tools/:"
if [ -d "tools" ]; then
ls -la tools/ 2>/dev/null | head -20
fiRepository: marcusquinn/aidevops
Length of output: 388
Correct the subagent reference paths — they point to non-existent locations.
The references to Vaultwarden and WordPress subagents use incorrect paths:
tools/credentials/vaultwarden.mdshould be../../tools/credentials/vaultwarden.md(actual path:.agent/tools/credentials/vaultwarden.md)tools/wordpress/should be../../tools/wordpress(actual path:.agent/tools/wordpress)
Update both paths to use proper relative references from .agent/services/hosting/cloudron.md.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~372-~372: The official name of this content management system is spelled with a capital “P”.
Context: ...anager troubleshooting - WordPress: tools/wordpress/ - WordPress-specific issues ## 📊 **...
(WORDPRESS)
🤖 Prompt for AI Agents
In @.agent/services/hosting/cloudron.md around lines 367 - 372, The two subagent
links in the App-Specific Troubleshooting section are incorrect; update the
Vaultwarden link `tools/credentials/vaultwarden.md` to the relative path
`../../tools/credentials/vaultwarden.md` and update the WordPress link
`tools/wordpress/` to `../../tools/wordpress` so they correctly point to
`.agent/tools/credentials/vaultwarden.md` and `.agent/tools/wordpress` from the
`cloudron.md` file; modify the entries under "App-Specific Troubleshooting" (the
Vaultwarden and WordPress bullet lines) accordingly.
- Replace misleading 'docker exec -it mysql mysql' with generic 'docker exec -it <container> /bin/bash' in quick reference - Add security reminder to redact secrets before sharing docker inspect output - Quote command substitution in MySQL root password command to prevent word splitting - Add security note about credential exposure in process list and docker inspect output - Change ambiguous '<app>' placeholder to '<app_subdomain>' for clarity in troubleshooting steps - Fix incorrect subagent reference paths for Vaultwarden and WordPress (use relative ../../ paths) - Fix trailing whitespace in SQL examples Closes #3819
…3868) - Replace misleading 'docker exec -it mysql mysql' with generic 'docker exec -it <container> /bin/bash' in quick reference - Add security reminder to redact secrets before sharing docker inspect output - Quote command substitution in MySQL root password command to prevent word splitting - Add security note about credential exposure in process list and docker inspect output - Change ambiguous '<app>' placeholder to '<app_subdomain>' for clarity in troubleshooting steps - Fix incorrect subagent reference paths for Vaultwarden and WordPress (use relative ../../ paths) - Fix trailing whitespace in SQL examples Closes #3819
…arcusquinn#3868) - Replace misleading 'docker exec -it mysql mysql' with generic 'docker exec -it <container> /bin/bash' in quick reference - Add security reminder to redact secrets before sharing docker inspect output - Quote command substitution in MySQL root password command to prevent word splitting - Add security note about credential exposure in process list and docker inspect output - Change ambiguous '<app>' placeholder to '<app_subdomain>' for clarity in troubleshooting steps - Fix incorrect subagent reference paths for Vaultwarden and WordPress (use relative ../../ paths) - Fix trailing whitespace in SQL examples Closes marcusquinn#3819
|
Completed via PR #5690. merged to main. |
- Shorten verbose title - Remove standalone 80/20 Rule section; merge into principle #8 - Remove filler intro sentence in Document Map - Collapse 6 '## Quick Reference: X' headers into single '## Quick Reference' with subsections - Compress intro prose in Core Principles - All code blocks, specs, benchmarks, links, and chapter refs preserved
…12451) - Shorten verbose title - Remove standalone 80/20 Rule section; merge into principle #8 - Remove filler intro sentence in Document Map - Collapse 6 '## Quick Reference: X' headers into single '## Quick Reference' with subsections - Compress intro prose in Core Principles - All code blocks, specs, benchmarks, links, and chapter refs preserved
The model was skipping or hardcoding the gh-signature-helper.sh footer when composing gh issue comment/create/pr create calls directly. The existing instruction at line 188 was correct but buried in prose. Added a numbered procedural checkpoint (#7) in the Error Prevention section — same pattern as the other 'before X, do Y' rules — making it a two-step procedure that's harder to skip. Renumbered prompt injection from #7 to #8 under Security Rules.
The signature footer instruction was moved from build.txt to AGENTS.md in 382ed63, after which the model started composing signatures inline — getting the runtime name wrong ('Claude Code' instead of 'OpenCode') and omitting version numbers, tokens, and session time. Root cause: build.txt is the highest-priority instruction set. Rules moved to AGENTS.md get lost in context during long sessions. The model then fabricates the signature from its own context instead of calling the helper. Changes: - Restore traceability constraints (PR title, Closes #NNN) to build.txt - Add signature footer as Error Prevention #8 with explicit NEVER-compose rule - AGENTS.md retains procedural details, points to build.txt for hard rules
The signature footer instruction was moved from build.txt to AGENTS.md in 382ed63, after which the model started composing signatures inline — getting the runtime name wrong ('Claude Code' instead of 'OpenCode') and omitting version numbers, tokens, and session time. Root cause: build.txt is the highest-priority instruction set. Rules moved to AGENTS.md get lost in context during long sessions. The model then fabricates the signature from its own context instead of calling the helper. Changes: - Restore traceability constraints (PR title, Closes #NNN) to build.txt - Add signature footer as Error Prevention #8 with explicit NEVER-compose rule - AGENTS.md retains procedural details, points to build.txt for hard rules
* fix: restore traceability and signature rules to build.txt The signature footer instruction was moved from build.txt to AGENTS.md in 382ed63, after which the model started composing signatures inline — getting the runtime name wrong ('Claude Code' instead of 'OpenCode') and omitting version numbers, tokens, and session time. Root cause: build.txt is the highest-priority instruction set. Rules moved to AGENTS.md get lost in context during long sessions. The model then fabricates the signature from its own context instead of calling the helper. Changes: - Restore traceability constraints (PR title, Closes #NNN) to build.txt - Add signature footer as Error Prevention #8 with explicit NEVER-compose rule - AGENTS.md retains procedural details, points to build.txt for hard rules * fix: use ref:GH#NNN (colon) not ref=GH#NNN (equals) in build.txt Aligns with AGENTS.md, TODO.md (884 colon vs 13 equals), and issue-sync-helper.sh parser which expects colon syntax. Pre-existing inconsistency caught by CodeRabbit.
…briefs Update epic and subtask briefs with: - Three concurrency modes: sequential, population-based, multi-dimension - Mailbox integration via mail-helper.sh discovery messages + convoy grouping - Inter-agent communication for concurrent multi-dimension research - Updated estimates (~25h total, up from ~20h) - Cross-dimension campaign summaries - Concurrency question (#8) in interactive setup flow
…atch on body quality claim-task-id.sh fallback path created issues with 'Task created via claim-task-id.sh' as body when no --description was passed. Neither claim-task-id.sh nor issue-sync-lib.sh appended provenance signature footers (build.txt rule #8). The pulse dispatched workers to these undescribed issues, wasting sessions. Fixes: - claim-task-id.sh: compose structured body from title when no --description; warn callers about the gap - claim-task-id.sh + issue-sync-lib.sh: append gh-signature-helper.sh footer to all created issues - pulse-wrapper.sh: skip issues with placeholder/empty bodies in deterministic fill floor dispatch Closes #17520
…atch on body quality (#17522) claim-task-id.sh fallback path created issues with 'Task created via claim-task-id.sh' as body when no --description was passed. Neither claim-task-id.sh nor issue-sync-lib.sh appended provenance signature footers (build.txt rule #8). The pulse dispatched workers to these undescribed issues, wasting sessions. Fixes: - claim-task-id.sh: compose structured body from title when no --description; warn callers about the gap - claim-task-id.sh + issue-sync-lib.sh: append gh-signature-helper.sh footer to all created issues - pulse-wrapper.sh: skip issues with placeholder/empty bodies in deterministic fill floor dispatch Closes #17520
1 participant
Summary
Changes
Quick Reference Section
New Troubleshooting Sections
Context
This improvement was prompted by a debugging session where 3 Vaultwarden instances were failing after a Cloudron update. The diagnosis required:
docker inspectThe existing subagent had no guidance for these common troubleshooting patterns.
Summary by CodeRabbit
Release Notes
✏️ Tip: You can customize this high-level summary in your review settings.