Skip to content

feat(cloudron): add git.cloudron.io as comprehensive reference source #249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcusquinn merged 3 commits into from
Jan 29, 2026
Merged

feat(cloudron): add git.cloudron.io as comprehensive reference source #249

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fe90d55
feat(cloudron): add git.cloudron.io as comprehensive reference source
marcusquinn Jan 29, 2026
87acce8
chore: log t082 for version sync inconsistency fix
marcusquinn Jan 29, 2026
f01fba5
refactor: extract git.cloudron.io reference into subagent
marcusquinn Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 41 additions & 11 deletions .agent/tools/deployment/cloudron-app-packaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ tools:

- **Purpose**: Package any web application for Cloudron deployment
- **Docs**: [docs.cloudron.io/packaging](https://docs.cloudron.io/packaging/tutorial/)
- **Examples**: [git.cloudron.io/cloudron](https://git.cloudron.io/cloudron) (all official apps)
- **Source Code**: [git.cloudron.io/packages](https://git.cloudron.io/packages) (200+ official app packages)
- **By Technology**: [git.cloudron.io/explore/projects/topics](https://git.cloudron.io/explore/projects/topics) (PHP, Node, Python, Go, etc.)
- **CLI**: `npm install -g cloudron` then `cloudron login my.cloudron.example`
- **Workflow**: `cloudron build && cloudron update --app testapp`
- **Debug**: `cloudron exec --app testapp` or `cloudron debug --app testapp`
Expand Down Expand Up @@ -77,6 +78,12 @@ Before starting to package an app, search the Cloudron forum for existing knowle

This research often saves significant trial-and-error, especially for apps with non-standard storage, auth, or process models.

## Using git.cloudron.io as Reference

Study real-world packaging patterns from 200+ official Cloudron app packages at https://git.cloudron.io/.

**Full guide**: `cloudron-git-reference.md` - Repository structure, finding apps by technology, GitLab API usage, recommended reference apps by use case, cloning patterns, and common search patterns.

## Overview

Cloudron app packaging creates Docker containers that integrate with Cloudron's platform features: automatic SSL, user management (LDAP/OIDC), backups, and addon services.
Expand Down Expand Up @@ -814,17 +821,40 @@ curl -v http://localhost:8000/health

## Resources

- **Official Docs**: https://docs.cloudron.io/packaging/
- **Example Apps**: https://git.cloudron.io/cloudron (all official packages)
- **Forum**: https://forum.cloudron.io/category/96/app-packaging-development
- **Base Image**: https://hub.docker.com/r/cloudron/base
### Official Documentation

- **Packaging Tutorial**: https://docs.cloudron.io/packaging/tutorial/
- **Packaging Reference**: https://docs.cloudron.io/packaging/
- **CLI Reference**: https://docs.cloudron.io/packaging/cli/
- **Publishing Guide**: https://docs.cloudron.io/packaging/publishing/
- **Addon Reference**: https://docs.cloudron.io/packaging/addons/

### git.cloudron.io (Source Code)

The GitLab instance at https://git.cloudron.io/ is the authoritative source for all Cloudron app packages. See "Using git.cloudron.io as Reference" section above for detailed usage.

| Resource | URL |
|----------|-----|
| **All Packages** | https://git.cloudron.io/packages |
| **Explore by Topic** | https://git.cloudron.io/explore/projects/topics |
| **Recently Updated** | https://git.cloudron.io/explore/projects?sort=latest_activity_desc |
| **Platform Code** | https://git.cloudron.io/platform |
| **Documentation Source** | https://git.cloudron.io/docs/docs |
Copy link

@gemini-code-assist gemini-code-assist bot Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The link for 'Documentation Source' (https://git.cloudron.io/docs/docs) appears to be broken, as it results in a 404 error for public access. The 'Repository Structure' table earlier in the document uses https://git.cloudron.io/docs, which links to the group. Please update this to a valid, accessible URL. If the repository is intended to be private, it might be better to remove this entry to avoid confusion.

| **GitLab API** | https://git.cloudron.io/api/v4/ |

### Example Repos by Framework

- **PHP**: https://git.cloudron.io/explore/projects?tag=php
- **Node.js**: https://git.cloudron.io/explore/projects?tag=node
- **Python**: https://git.cloudron.io/explore/projects?tag=python
- **Go**: https://git.cloudron.io/explore/projects?tag=go
- **Ruby/Rails**: https://git.cloudron.io/explore/projects?tag=rails
- **Java**: https://git.cloudron.io/explore/projects?tag=java
| Framework | Topic URL | Example App |
|-----------|-----------|-------------|
| PHP | https://git.cloudron.io/explore/projects/topics/php | nextcloud-app, wordpress-app |
| Node.js | https://git.cloudron.io/explore/projects/topics/node | ghost-app, nodebb-app |
| Python | https://git.cloudron.io/explore/projects/topics/python | synapse-app |
| Go | https://git.cloudron.io/explore/projects/topics/go | vikunja-app |
| Ruby/Rails | https://git.cloudron.io/explore/projects/topics/rails | discourse-app |
| Java | https://git.cloudron.io/explore/projects/topics/java | metabase-app |

### Other Resources

- **Forum (Packaging)**: https://forum.cloudron.io/category/96/app-packaging-development
- **Base Image Tags**: https://hub.docker.com/r/cloudron/base/tags
- **App Store**: https://cloudron.io/store/index.html
124 changes: 124 additions & 0 deletions .agent/tools/deployment/cloudron-git-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
description: Reference guide for using git.cloudron.io to study Cloudron app packaging patterns
mode: subagent
tools:
read: true
bash: true
webfetch: true
---

# Using git.cloudron.io as Reference

The Cloudron GitLab instance at https://git.cloudron.io/ hosts all official app packages and is the authoritative source for packaging patterns. Use it to study real-world implementations when packaging new apps.

## Repository Structure

| Group | URL | Purpose |
|-------|-----|---------|
| `packages` | https://git.cloudron.io/packages | Official app packages (200+ apps) |
| `playground` | https://git.cloudron.io/playground | Incubator for new/experimental packages |
| `platform` | https://git.cloudron.io/platform | Cloudron platform code (box, base images) |
| `docs` | https://git.cloudron.io/docs | Official documentation source |
| `apps` | https://git.cloudron.io/apps | Apps developed by Cloudron.io team |
| `utils` | https://git.cloudron.io/utils | Tools and utilities |

## Finding Reference Apps by Technology

Browse apps by topic/tag to find packages using similar technology stacks:

| Technology | URL | Count |
|------------|-----|-------|
| PHP | https://git.cloudron.io/explore/projects/topics/php | 21+ |
| Go | https://git.cloudron.io/explore/projects/topics/go | 11+ |
| Node.js | https://git.cloudron.io/explore/projects/topics/node | 10+ |
| Java | https://git.cloudron.io/explore/projects/topics/java | 10+ |
| Python | https://git.cloudron.io/explore/projects/topics/python | 6+ |
| Ruby/Rails | https://git.cloudron.io/explore/projects/topics/rails | 4+ |
| nginx | https://git.cloudron.io/explore/projects/topics/nginx | 6+ |
| Apache | https://git.cloudron.io/explore/projects/topics/apache | 4+ |
| Supervisor | https://git.cloudron.io/explore/projects/topics/supervisor | 2+ |

**All topics**: https://git.cloudron.io/explore/projects/topics

## GitLab API for Programmatic Access

The GitLab API enables searching and fetching package code programmatically:

```bash
# List all packages group projects
curl -s "https://git.cloudron.io/api/v4/groups/packages/projects?per_page=100"

# Search projects by topic
curl -s "https://git.cloudron.io/api/v4/projects?topic=php&per_page=20"

# Get repository file tree
curl -s "https://git.cloudron.io/api/v4/projects/packages%2Fghost-app/repository/tree"

# Get raw file content
curl -s "https://git.cloudron.io/api/v4/projects/packages%2Fghost-app/repository/files/start.sh/raw?ref=master"

# Search for code patterns across repos (requires auth for some endpoints)
curl -s "https://git.cloudron.io/api/v4/projects/packages%2Fghost-app/search?scope=blobs&search=supervisord"
```

## Recommended Reference Apps by Use Case

When packaging a new app, study these well-maintained packages as templates:

| Use Case | Reference App | Why |
|----------|---------------|-----|
| **Node.js + nginx** | [ghost-app](https://git.cloudron.io/packages/ghost-app) | Clean supervisor setup, nginx proxy |
| **PHP + nginx** | [nextcloud-app](https://git.cloudron.io/packages/nextcloud-app) | Complex PHP app, cron, background jobs |
| **PHP + Apache** | [wordpress-app](https://git.cloudron.io/packages/wordpress-app) | Apache config, plugin handling |
| **Python + nginx** | [synapse-app](https://git.cloudron.io/packages/synapse-app) | Python virtualenv, complex config |
| **Go binary** | [vikunja-app](https://git.cloudron.io/packages/vikunja-app) | Simple Go app with nginx frontend |
| **Java/JVM** | [metabase-app](https://git.cloudron.io/packages/metabase-app) | JVM memory tuning, startup scripts |
| **Ruby/Rails** | [discourse-app](https://git.cloudron.io/packages/discourse-app) | Complex Rails app, sidekiq workers |
| **Multi-process** | [peertube-app](https://git.cloudron.io/packages/peertube-app) | Supervisor with multiple workers |
| **LDAP/OIDC auth** | [grafana-app](https://git.cloudron.io/packages/grafana-app) | Auth integration patterns |
| **Media handling** | [jellyfin-app](https://git.cloudron.io/packages/jellyfin-app) | Large file handling, transcoding |

## What to Study in Reference Apps

When examining a reference package, focus on these files:

1. **CloudronManifest.json** - Addon requirements, memory limits, health check path
2. **Dockerfile** - Base image choice, build steps, file permissions
3. **start.sh** - Initialization sequence, config injection, symlink patterns
4. **nginx/*.conf** or **apache/*.conf** - Web server configuration
5. **supervisor/*.conf** - Multi-process orchestration (if used)
6. **CHANGELOG.md** - Version history and migration patterns

## Cloning for Local Study

```bash
# Clone a reference app for local study
git clone https://git.cloudron.io/packages/ghost-app.git

# Or use sparse checkout for specific files
git clone --filter=blob:none --sparse https://git.cloudron.io/packages/ghost-app.git
cd ghost-app
git sparse-checkout set start.sh Dockerfile CloudronManifest.json
```

## Finding Solutions to Specific Problems

When facing a specific packaging challenge, search across all packages:

```bash
# Find apps using supervisord
curl -s "https://git.cloudron.io/api/v4/projects?topic=supervisor"

# Find apps with proxyAuth (Cloudron handles auth)
curl -s "https://git.cloudron.io/api/v4/projects?topic=proxyAuth"

# Browse recently updated packages (most active/maintained)
# Visit: https://git.cloudron.io/explore/projects?sort=latest_activity_desc
```

**Common patterns to search for**:
- `gosu cloudron:cloudron` - Privilege dropping
- `ln -sfn /app/data` - Symlink patterns for writable paths
- `CLOUDRON_POSTGRESQL_` - Database configuration
- `supervisord.conf` - Multi-process setup
- `envsubst` - Template-based config injection
Comment on lines +10 to +124
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Replace inline code blocks with progressive-disclosure pointers and file:line references.

This .agent/**/*.md file includes multiple inline bash snippets and extensive inline guidance, which conflicts with the requirement to use progressive disclosure and reference actual implementations via file:line. Please refactor this doc to link out to subagents or file:line references instead of embedding code blocks.
As per coding guidelines: “.agent/**/*.md: Apply progressive disclosure pattern by using pointers to subagents rather than including inline content in agent documentation. Include code examples only when authoritative; use file:line references to point to actual implementation instead of inline code snippets.”

Based on learnings: “All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truth.”

🤖 Prompt for AI Agents 
In @.agent/tools/deployment/cloudron-git-reference.md around lines 10 - 124,
This doc embeds multiple inline bash/code snippets and operational guidance;
refactor cloudron-git-reference.md to follow the progressive-disclosure pattern
by removing inline code blocks (e.g., embedded bash examples and the curl
snippets) and replacing them with pointers to subagents or explicit file:line
references pointing at real implementations (use examples like start.sh,
Dockerfile, CloudronManifest.json, supervisord.conf, nginx/*.conf, and
occurrences such as `gosu cloudron:cloudron`, `ln -sfn /app/data`, and
`envsubst` to show where to link), and move any authoritative instruction text
into AGENTS.md as the single source of truth while leaving only concise pointers
and links in this file.

2 changes: 2 additions & 0 deletions TODO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ Tasks with no open blockers - ready to work on. Use `/ready` to refresh this lis

## Backlog

- [ ] t082 Fix version sync inconsistency (VERSION vs package.json/setup.sh/aidevops.sh) #bugfix ~15m (ai:10m test:5m) logged:2026-01-29
- Notes: Release commit bd0695c bumped VERSION to 2.92.1 but missed syncing package.json, setup.sh, aidevops.sh, sonar-project.properties, .claude-plugin/marketplace.json. Either fix manually or ensure version-manager.sh is used for all releases.
Comment on lines +55 to +56
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Task t082 is missing from TOON machine-readable block.

The new task t082 is added to the human-readable Backlog section but is absent from the <!--TOON:backlog[52]...--> block (lines 196-272). This inconsistency will break tools that parse TOON blocks for task management, sync with Beads, or generate reports.

🔧 Resolution options
  1. Run beads-sync-helper.sh sync to regenerate TOON blocks from human-readable content
  2. Manually add t082 entry to the TOON:backlog block following the schema at line 196
  3. Use toon-helper.sh validate TODO.md to check for additional inconsistencies
🤖 Prompt for AI Agents 
In `@TODO.md` around lines 55 - 56, The TODO.md file has a mismatch: the
human-readable Backlog added task t082 but the machine-readable TOON block
(`<!--TOON:backlog[52]...-->`) is missing the t082 entry; fix this by updating
the TOON backlog block to include the t082 item following the existing schema
used in the block (match ID, title, tags, estimates and logged info as in the
human-readable line), or regenerate the TOON block by running
beads-sync-helper.sh sync; after updating run toon-helper.sh validate TODO.md to
ensure no other inconsistencies remain.

- [ ] t068 Multi-Agent Orchestration & Token Efficiency #plan → [todo/PLANS.md#2026-01-23-multi-agent-orchestration--token-efficiency] ~5d (ai:3d test:1d read:1d) logged:2026-01-23 started:2026-01-23T00:00Z
- [x] t068.1 Custom System Prompt (prompts/build.txt) ~2h blocked-by:none completed:2026-01-24
- [x] t068.2 Compaction Plugin (opencode-aidevops-plugin) ~4h blocked-by:t068.1 completed:2026-01-24
Expand Down
Loading