feat: add cloudron-app-packaging subagent for custom app development #190
Conversation
Add comprehensive guidance for packaging applications for Cloudron: - Decision trees for base image and addon selection - Filesystem permissions and symlink dance patterns - start.sh architecture with multi-process support - Framework-specific patterns (PHP, Node.js, Python, Go, static) - Helper script with scaffold, validate, build, test commands - Anti-patterns and troubleshooting guidance Based on official Cloudron docs and community best practices from forum.cloudron.io/topic/14939
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 enhances the developer experience for creating and managing custom applications on the Cloudron platform. By providing both an extensive guide and an automated helper script, it aims to standardize packaging practices, reduce common errors, and accelerate the development and deployment cycle for Cloudron applications. The changes offer clear instructions and tools for developers to efficiently integrate their applications with Cloudron's ecosystem. 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
|
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughIntroduces a comprehensive Cloudron app packaging CLI tool with 13 commands for initializing, validating, building, and managing Cloudron applications, complemented by detailed deployment documentation and registry index updates registering the new automation components. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the 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. Comment |
🔍 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: Sun Jan 25 01:35:19 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 introduces a comprehensive subagent for Cloudron app packaging, including a detailed guide and a powerful helper script. The additions are well-structured and provide significant value for developers packaging applications for Cloudron. The script is robust and covers the entire development workflow, from initialization to testing. The documentation is thorough and provides excellent patterns and anti-patterns.
My review includes a few suggestions to enhance the robustness of the helper script and improve consistency between the script's templates and the documentation. Specifically, I've recommended adding confirmation prompts to prevent accidental file overwrites in the scaffolding commands and aligning the PHP scaffold template with the best practices outlined in the guide.
| esac | ||
| } | ||
|
|
||
| scaffold_php() { |
There was a problem hiding this comment.
The scaffold commands, including this one, overwrite existing files like Dockerfile and start.sh without confirmation. This can lead to accidental data loss if a user has already made customizations. It's highly recommended to add a confirmation prompt before overwriting any files.
This can be done by adding a check at the beginning of this function, and similarly for scaffold_node, scaffold_python, scaffold_go, and scaffold_static.
Example implementation:
if [[ -f "Dockerfile" || -f "start.sh" ]]; then
log_warn "This will overwrite existing Dockerfile and start.sh"
read -rp "Continue? [y/N] " confirm
if ! [[ "$confirm" =~ ^[Yy]$ ]]; then
log_info "Scaffold cancelled."
return 0
fi
fi| RUN mkdir -p /app/code/defaults && \ | ||
| mv /app/code/config /app/code/defaults/config 2>/dev/null || true |
There was a problem hiding this comment.
The Dockerfile template for the PHP scaffold only preserves the config directory. However, the corresponding start.sh template also creates a symlink for a storage directory. To be consistent and prevent potential loss of default data, you should also move the storage directory to /app/code/defaults.
This aligns with the 'Symlink Dance' pattern described in cloudron-app-packaging.md.
| RUN mkdir -p /app/code/defaults && \ | |
| mv /app/code/config /app/code/defaults/config 2>/dev/null || true | |
| RUN mkdir -p /app/code/defaults && \ | |
| mv /app/code/config /app/code/defaults/config 2>/dev/null || true && \ | |
| mv /app/code/storage /app/code/defaults/storage 2>/dev/null || true |
| # First-run initialization | ||
| if [[ "$FIRST_RUN" == "true" ]]; then | ||
| cp -rn /app/code/defaults/config/* /app/data/config/ 2>/dev/null || true | ||
| fi |
There was a problem hiding this comment.
The start.sh template for the PHP scaffold only copies default files for the config directory on first run. Since the storage directory is also part of the symlink dance for many PHP apps (like Laravel, etc.), you should also copy its default contents to ensure consistency.
| # First-run initialization | |
| if [[ "$FIRST_RUN" == "true" ]]; then | |
| cp -rn /app/code/defaults/config/* /app/data/config/ 2>/dev/null || true | |
| fi | |
| # First-run initialization | |
| if [[ "$FIRST_RUN" == "true" ]]; then | |
| cp -rn /app/code/defaults/config/* /app/data/config/ 2>/dev/null || true | |
| cp -rn /app/code/defaults/storage/* /app/data/storage/ 2>/dev/null || true | |
| fi |
| RUN mkdir -p /app/code/defaults && \ | ||
| mv /app/code/config /app/code/defaults/config && \ | ||
| mv /app/code/storage /app/code/defaults/storage |
There was a problem hiding this comment.
The mv commands in this Dockerfile example can cause the build to fail if the config or storage directories do not exist in the application code. It's safer to make these commands optional, as done in the helper script's templates. This makes the pattern more robust and applicable to a wider range of applications.
| RUN mkdir -p /app/code/defaults && \ | |
| mv /app/code/config /app/code/defaults/config && \ | |
| mv /app/code/storage /app/code/defaults/storage | |
| RUN mkdir -p /app/code/defaults && \ | |
| mv /app/code/config /app/code/defaults/config 2>/dev/null || true && \ | |
| mv /app/code/storage /app/code/defaults/storage 2>/dev/null || true |
🤖 Augment PR SummarySummary: This PR adds Cloudron packaging support to aidevops by introducing a new deployment subagent and a helper script for common Cloudron CLI workflows. Changes:
Technical Notes: The helper script runs with 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| FROM cloudron/base:5.0.0 | ||
|
|
||
| # Install dependencies | ||
| RUN apt-get update && apt-get install -y --no-install-recommends \ |
There was a problem hiding this comment.
The generated Dockerfile template here uses a line-continuation (\) before a comment line, which will cause the shell to treat the rest of the RUN line (including && rm -rf ...) as commented out and can even make apt-get install run with no packages. This means the default Dockerfile produced by init may fail to build until edited.
🤖 Was this useful? React with 👍 or 👎
| # Check required fields | ||
| local required_fields=("id" "title" "version" "healthCheckPath" "httpPort" "manifestVersion") | ||
| for field in "${required_fields[@]}"; do | ||
| if ! echo "$manifest" | jq -e ".$field" > /dev/null 2>&1; then |
There was a problem hiding this comment.
cmd_validate/cmd_status rely on jq, but the script never checks that jq is installed; with set -euo pipefail this will exit abruptly with command not found. Consider a dependency check (similar to check_cloudron_cli) so users get a clear error message.
🤖 Was this useful? React with 👍 or 👎
| # Check httpPort is a number | ||
| local http_port | ||
| http_port=$(echo "$manifest" | jq -r '.httpPort // "null"') | ||
| if ! [[ "$http_port" =~ ^[0-9]+$ ]]; then |
There was a problem hiding this comment.
This check only validates that httpPort is numeric, but the error message says “positive integer” and it doesn’t reject 0 or out-of-range values. Tightening validation to 1..65535 would make validate more accurate.
🤖 Was this useful? React with 👍 or 👎
Address code review feedback: - Add confirmation prompt before overwriting existing files in all scaffold commands - Include storage directory in PHP scaffold defaults preservation - Copy storage defaults on first-run in PHP scaffold - Make mv commands in documentation examples safe with 2>/dev/null || true
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @.agent/scripts/cloudron-package-helper.sh:
- Around line 170-186: In cmd_validate the use of the arithmetic post-increment
((errors++)) can return a non-zero exit status under set -e and cause premature
script exit; replace each ((errors++)) with a safe increment using assignment
like errors=$((errors+1)) (this evaluates to a normal exit status), and apply
the same replacement for every other place in the script that increments the
errors variable (all occurrences of ((errors++)) in this file).
- Around line 170-235: The script uses jq in cmd_validate (and cmd_status) but
never verifies it exists; add a helper function check_jq that tests for jq
(e.g., command -v jq) and emits a clear log_error if missing and returns
non-zero, then call check_jq || return 1 at the start of cmd_validate and
cmd_status so the functions fail fast with a helpful message instead of
producing confusing errors; reference the symbols check_jq, cmd_validate, and
cmd_status when making the changes.
🧹 Nitpick comments (1)
.agent/tools/deployment/cloudron-app-packaging.md (1)
37-37: Minor: Markdown linting flags missing blank lines around fenced code blocks.Static analysis reports MD031 violations at multiple locations. While this doesn't affect functionality, adding blank lines before/after code fences improves rendering consistency across Markdown processors.
Also applies to: 46-46, 138-138, 275-275, 321-321, 456-456, 750-750, 757-757, 764-764, 772-772, 779-779
🔍 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: Sun Jan 25 01:39:02 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
- Add check_jq() function to verify jq is installed - Add jq check to cmd_validate and cmd_status functions - Replace ((errors++)) with errors=$((errors + 1)) to avoid exit status issues under set -e
|
🔍 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: Sun Jan 25 01:42:26 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
1 participant
Summary
cloudron-app-packaging.mdsubagent with guidance for packaging custom applications for Cloudron deploymentcloudron-package-helper.shscript with scaffold, validate, build, and test commandssubagent-index.toonto include new subagent and scriptFeatures
Subagent (
cloudron-app-packaging.md)Helper Script (
cloudron-package-helper.sh)init [name]- Initialize new Cloudron app package with templatesscaffold <type>- Generate boilerplate for php, node, python, go, staticvalidate- Validate CloudronManifest.jsonbuild- Build Docker imageinstall <location>- Install app on Cloudronupdate [app]- Build and update installed applogs/exec/debug- Debugging commandstest- Show validation checkliststatus- Show current package statusContext
Based on:
Testing
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.