diff --git a/.agents/configs/skill-sources.json b/.agents/configs/skill-sources.json index 39c4c33ce..886f23c3a 100644 --- a/.agents/configs/skill-sources.json +++ b/.agents/configs/skill-sources.json @@ -93,6 +93,39 @@ "last_checked": "2026-01-29T01:37:00Z", "merge_strategy": "added", "notes": "SEO audit skill from marketingskills repo (skills/seo-audit subpath), includes references/" + }, + { + "name": "cloudron-app-packaging", + "upstream_url": "https://git.cloudron.io/docs/skills", + "upstream_commit": "b247b124d168730051186aa63afad87c0c1f5a52", + "local_path": ".agents/tools/deployment/cloudron-app-packaging-skill.md", + "format_detected": "skill-md-nested", + "imported_at": "2026-03-01T18:00:00Z", + "last_checked": "2026-03-01T18:00:00Z", + "merge_strategy": "added", + "notes": "Official Cloudron skill from git.cloudron.io/docs/skills. Includes manifest-ref.md and addons-ref.md in cloudron-app-packaging-skill/" + }, + { + "name": "cloudron-app-publishing", + "upstream_url": "https://git.cloudron.io/docs/skills", + "upstream_commit": "b247b124d168730051186aa63afad87c0c1f5a52", + "local_path": ".agents/tools/deployment/cloudron-app-publishing-skill.md", + "format_detected": "skill-md", + "imported_at": "2026-03-01T18:00:00Z", + "last_checked": "2026-03-01T18:00:00Z", + "merge_strategy": "added", + "notes": "Official Cloudron skill for CloudronVersions.json publishing and community packages (9.1+)" + }, + { + "name": "cloudron-server-ops", + "upstream_url": "https://git.cloudron.io/docs/skills", + "upstream_commit": "b247b124d168730051186aa63afad87c0c1f5a52", + "local_path": ".agents/tools/deployment/cloudron-server-ops-skill.md", + "format_detected": "skill-md", + "imported_at": "2026-03-01T18:00:00Z", + "last_checked": "2026-03-01T18:00:00Z", + "merge_strategy": "added", + "notes": "Official Cloudron skill for CLI server operations (logs, exec, backups, env vars, CI/CD)" } ] } diff --git a/.agents/services/hosting/cloudron.md b/.agents/services/hosting/cloudron.md index f59d5816b..f291e0a00 100644 --- a/.agents/services/hosting/cloudron.md +++ b/.agents/services/hosting/cloudron.md @@ -18,13 +18,13 @@ tools: ## Quick Reference - **Type**: Self-hosted app platform (100+ apps), auto-updates/backups/SSL -- **Auth**: API token from Dashboard > Settings > API Access +- **Auth**: API token from Dashboard > Settings > API Access (9.1+: passkey/OIDC login) - **Config**: `configs/cloudron-config.json` - **Commands**: `cloudron-helper.sh [servers|connect|status|apps|install-app|update-app|restart-app|logs|backup-app|domains|add-domain|users|add-user] [server] [args]` +- **CLI ops**: `cloudron-server-ops-skill.md` (full CLI reference from upstream) +- **Packaging**: `cloudron-app-packaging.md` (native guide), `cloudron-app-packaging-skill.md` (upstream skill) +- **Publishing**: `cloudron-app-publishing-skill.md` (community packages via CloudronVersions.json) - **API test**: `curl -H "Authorization: Bearer TOKEN" https://cloudron.domain.com/api/v1/cloudron/status` -- **App ops**: `install-app [server] [app] [subdomain]`, `update-app`, `restart-app`, `logs` -- **Backup**: `backup-system`, `backup-app`, `list-backups`, `restore-backup` -- **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 `, `docker exec -it mysql mysql` @@ -33,17 +33,33 @@ tools: Cloudron is a complete solution for running apps on your server, providing easy app installation, automatic updates, backups, and domain management. +## What's New in 9.1 + +Cloudron 9.1 (released to unstable 2026-03-01) introduces major features: + +- **Custom app build and deploy**: `cloudron install` uploads package source and builds on-server. Source is backed up and rebuilt on restore. CLI-driven workflow for developers building custom apps or patching existing packages. +- **Community packages**: Install third-party apps from a `CloudronVersions.json` URL via the dashboard. Cloudron tracks the URL and auto-checks for updates. See `cloudron-app-publishing-skill.md`. +- **Passkey authentication**: FIDO2/WebAuthn passkey support for Cloudron login. Tested with Bitwarden, YubiKey 5, Nitrokey, and native browser/OS support. +- **OIDC CLI login**: CLI uses browser-based OIDC login to support passkeys. Pre-obtained API tokens still work for CI/CD pipelines. +- **Addon upgrades**: MongoDB 8, Redis 8.4, Node.js 24.x +- **ACME ARI support**: RFC 9773 for certificate renewal information +- **Backup integrity verification UI**: Verify backup integrity from the dashboard +- **Improved progress reporting**: Percentage complete and elapsed/estimated time for backups and installations +- **Better event log UI**: Separate notifications view + +**Source**: [forum.cloudron.io/topic/14976](https://forum.cloudron.io/topic/14976/what-s-coming-in-9-1) + ## Provider Overview ### **Cloudron Characteristics:** - **Service Type**: Self-hosted app platform and server management -- **App Ecosystem**: 100+ pre-configured apps available +- **App Ecosystem**: 100+ pre-configured apps + community packages (9.1+) - **Management**: Web-based dashboard for complete server management - **Automation**: Automatic updates, backups, and SSL certificates - **Multi-tenancy**: Support for multiple users and domains - **API Support**: REST API for automation and integration -- **Security**: Built-in firewall, automatic security updates +- **Security**: Built-in firewall, automatic security updates, passkey auth (9.1+) ### **Best Use Cases:** @@ -479,4 +495,16 @@ done --- -**Cloudron provides a comprehensive app platform with excellent management capabilities, making it ideal for organizations needing easy-to-manage, self-hosted applications.** 🚀 +## Related Skills and Subagents + +| Resource | Path | Purpose | +|----------|------|---------| +| App packaging (native) | `tools/deployment/cloudron-app-packaging.md` | Full packaging guide with aidevops helper scripts | +| App packaging (upstream) | `tools/deployment/cloudron-app-packaging-skill.md` | Official Cloudron skill with manifest/addon refs | +| App publishing | `tools/deployment/cloudron-app-publishing-skill.md` | CloudronVersions.json and community packages | +| Server ops | `tools/deployment/cloudron-server-ops-skill.md` | Full CLI reference for managing installed apps | +| Git reference | `tools/deployment/cloudron-git-reference.md` | Using git.cloudron.io for packaging patterns | +| Helper script | `scripts/cloudron-helper.sh` | Multi-server management via API | +| Package helper | `scripts/cloudron-package-helper.sh` | Local packaging development workflow | + +**Cloudron provides a comprehensive app platform with excellent management capabilities, making it ideal for organizations needing easy-to-manage, self-hosted applications.** diff --git a/.agents/subagent-index.toon b/.agents/subagent-index.toon index 489bbde6a..d70975fd4 100644 --- a/.agents/subagent-index.toon +++ b/.agents/subagent-index.toon @@ -23,7 +23,7 @@ pro,gemini-2.5-pro,Capable large context grok,grok-3,Research and real-time web knowledge --> - + +## Quick Reference + +- **Purpose**: Official upstream skill for Cloudron app packaging +- **Upstream**: [git.cloudron.io/docs/skills](https://git.cloudron.io/docs/skills) (`cloudron-app-packaging`) +- **Docs**: [docs.cloudron.io/packaging](https://docs.cloudron.io/packaging/) +- **Reference files**: `cloudron-app-packaging-skill/manifest-ref.md`, `cloudron-app-packaging-skill/addons-ref.md` +- **Also see**: `cloudron-app-packaging.md` (native aidevops guide with helper scripts and local dev workflow) + + + +## Quick Start + +```bash +npm install -g cloudron +cloudron login my.example.com +cloudron init # creates CloudronManifest.json and Dockerfile +cloudron install # uploads source, builds on server, installs app +cloudron update # re-uploads, rebuilds, updates running app +``` + +## Key Constraints + +- Filesystem is **readonly** at runtime. Writable dirs: `/tmp`, `/run`, `/app/data`. +- Databases, caching, email, and auth are **addons** -- env vars injected at runtime. +- `CloudronManifest.json` declares metadata, ports, and addon requirements. +- App listens on HTTP (not HTTPS). The platform handles TLS termination. +- Default memory limit is 256 MB (RAM + swap). Set `memoryLimit` in manifest to change. + +## Build Methods (9.1+) + +### On-Server Build (Default, Recommended) + +`cloudron install` and `cloudron update` upload the source and build on the server. No local Docker needed. Source is part of the app backup -- on restore, the app rebuilds from the backed-up source. + +```bash +cloudron install --location myapp # uploads, builds, installs +cloudron update --app myapp # uploads, rebuilds, updates +``` + +### Local Docker Build + +Build locally, push to registry, install with image: + +```bash +docker login +cloudron build # builds, tags, pushes +cloudron install # detects the built image +cloudron build && cloudron update # update cycle +``` + +### Build Service + +Offload builds to a remote Docker Builder App: + +```bash +cloudron build login # authenticate with build service +cloudron build # source sent to remote builder +``` + +## Dockerfile Patterns + +Name the file `Dockerfile`, `Dockerfile.cloudron`, or `cloudron/Dockerfile`. + +### Typical Structure + +```dockerfile +FROM cloudron/base:5.0.0@sha256:... + +RUN mkdir -p /app/code +WORKDIR /app/code + +# Install app +COPY . /app/code/ + +# Create symlinks for runtime config +RUN ln -sf /run/app/config.json /app/code/config.json + +# Ensure start script is executable +RUN chmod +x /app/code/start.sh + +CMD [ "/app/code/start.sh" ] +``` + +### start.sh Conventions + +- Runs as root. Use `gosu cloudron:cloudron ` to drop privileges. +- Fix ownership on every start (backups/restores can reset it): + + ```bash + chown -R cloudron:cloudron /app/data + ``` + +- Use `exec` as the last command to forward SIGTERM: + + ```bash + exec gosu cloudron:cloudron node /app/code/server.js + ``` + +- Track first-run with a marker file: + + ```bash + if [[ ! -f /app/data/.initialized ]]; then + # first-time setup + touch /app/data/.initialized + fi + ``` + +### Writable Directories + +| Path | Persists across restarts | Backed up | +|------|--------------------------|-----------| +| `/tmp` | No | No | +| `/run` | No | No | +| `/app/data` | Yes | Yes (requires `localstorage` addon) | + +### Logging + +Log to stdout/stderr. The platform manages rotation and streaming. If the app cannot log to stdout, write to `/run//*.log` (two levels deep). These files are autorotated. + +### Multiple Processes + +Use `supervisor` or `pm2` when the app has multiple components. Configure supervisor to send output to stdout: + +```ini +[program:app] +stdout_logfile=/dev/stdout +stdout_logfile_maxbytes=0 +stderr_logfile=/dev/stderr +stderr_logfile_maxbytes=0 +``` + +### Memory-Aware Worker Count + +```bash +if [[ -f /sys/fs/cgroup/cgroup.controllers ]]; then + memory_limit=$(cat /sys/fs/cgroup/memory.max) + [[ "${memory_limit}" == "max" ]] && memory_limit=$((2 * 1024 * 1024 * 1024)) +else + memory_limit=$(cat /sys/fs/cgroup/memory/memory.limit_in_bytes) +fi +worker_count=$((memory_limit / 1024 / 1024 / 150)) +worker_count=$((worker_count > 8 ? 8 : worker_count)) +worker_count=$((worker_count < 1 ? 1 : worker_count)) +``` + +## Manifest Essentials + +Minimal `CloudronManifest.json`: + +```json +{ + "id": "com.example.myapp", + "title": "My App", + "author": "Jane Developer ", + "version": "1.0.0", + "healthCheckPath": "/", + "httpPort": 8000, + "addons": { + "localstorage": {} + }, + "manifestVersion": 2 +} +``` + +For the full field reference, see [manifest-ref.md](cloudron-app-packaging-skill/manifest-ref.md). + +## Addons Overview + +| Addon | Provides | Key env var | +|-------|----------|-------------| +| `localstorage` | Writable `/app/data`, backup support | -- | +| `mysql` | MySQL 8.0 database | `CLOUDRON_MYSQL_URL` | +| `postgresql` | PostgreSQL 14.9 database | `CLOUDRON_POSTGRESQL_URL` | +| `mongodb` | MongoDB 8.0 database | `CLOUDRON_MONGODB_URL` | +| `redis` | Redis 8.4 cache (persistent) | `CLOUDRON_REDIS_URL` | +| `ldap` | LDAP v3 authentication | `CLOUDRON_LDAP_URL` | +| `oidc` | OpenID Connect authentication | `CLOUDRON_OIDC_DISCOVERY_URL` | +| `sendmail` | Outgoing email (SMTP relay) | `CLOUDRON_MAIL_SMTP_SERVER` | +| `recvmail` | Incoming email (IMAP) | `CLOUDRON_MAIL_IMAP_SERVER` | +| `proxyauth` | Authentication wall | -- | +| `scheduler` | Cron-like periodic tasks | -- | +| `tls` | App certificate files | `/etc/certs/tls_cert.pem` | +| `docker` | Create containers (restricted) | `CLOUDRON_DOCKER_HOST` | + +Read env vars at runtime on every start -- values can change across restarts. Run DB migrations on each start. + +For full env var lists and addon options, see [addons-ref.md](cloudron-app-packaging-skill/addons-ref.md). + +## Stack-Specific Notes + +**Apache** -- Disable default sites, set `Listen 8000`, log errors to stderr, start with `exec /usr/sbin/apache2 -DFOREGROUND`. + +**Nginx** -- Use `/run/` for temp paths (`client_body_temp_path`, `proxy_temp_path`, etc.). Run with supervisor alongside the app. + +**PHP** -- Move sessions from `/var/lib/php/sessions` to `/run/php/sessions` via symlink. + +**Java** -- Read cgroup memory limit and set `-XX:MaxRAM` accordingly. + +## Debugging + +```bash +cloudron logs # view app logs +cloudron logs -f # follow logs in real time +cloudron exec # shell into running app +cloudron debug # pause app (read-write filesystem) +cloudron debug --disable # exit debug mode +``` + +## Examples + +All published Cloudron apps are open source: https://git.cloudron.io/packages + +Browse by framework: +[PHP](https://git.cloudron.io/explore/projects?tag=php) | +[Node](https://git.cloudron.io/explore/projects?tag=node) | +[Python](https://git.cloudron.io/explore/projects?tag=python) | +[Ruby/Rails](https://git.cloudron.io/explore/projects?tag=rails) | +[Java](https://git.cloudron.io/explore/projects?tag=java) | +[Go](https://git.cloudron.io/explore/projects?tag=go) | +[Rust](https://git.cloudron.io/explore/projects?tag=rust) diff --git a/.agents/tools/deployment/cloudron-app-packaging-skill/addons-ref.md b/.agents/tools/deployment/cloudron-app-packaging-skill/addons-ref.md new file mode 100644 index 000000000..043d5d015 --- /dev/null +++ b/.agents/tools/deployment/cloudron-app-packaging-skill/addons-ref.md @@ -0,0 +1,248 @@ +# Addons Reference + +Full environment variable and option reference for Cloudron addons. Declare addons in `CloudronManifest.json` under the `addons` key. + +Read env vars at runtime on every start — values can change across restarts. + +## localstorage + +Provides writable `/app/data` directory. Contents are backed up. Directory is empty on first install; files from the Docker image are not present. Restore permissions in `start.sh`. + +Options: + +- `ftp` — Enable FTP access: `{ "ftp": { "uid": 33, "uname": "www-data" } }` +- `sqlite` — Declare SQLite files for consistent backup: `{ "sqlite": { "paths": ["/app/data/db.sqlite"] } }` + +## mysql + +MySQL 8.0. Database is pre-created. + +```text +CLOUDRON_MYSQL_URL # full connection URL +CLOUDRON_MYSQL_USERNAME +CLOUDRON_MYSQL_PASSWORD +CLOUDRON_MYSQL_HOST +CLOUDRON_MYSQL_PORT +CLOUDRON_MYSQL_DATABASE +``` + +Options: + +- `multipleDatabases: true` — Provides `CLOUDRON_MYSQL_DATABASE_PREFIX` instead of `CLOUDRON_MYSQL_DATABASE`. Create databases with that prefix. + +Default charset: `utf8mb4` / `utf8mb4_unicode_ci`. + +Debug: `cloudron exec` then `mysql --user=$CLOUDRON_MYSQL_USERNAME --password=$CLOUDRON_MYSQL_PASSWORD --host=$CLOUDRON_MYSQL_HOST $CLOUDRON_MYSQL_DATABASE` + +## postgresql + +PostgreSQL 14.9. + +```text +CLOUDRON_POSTGRESQL_URL +CLOUDRON_POSTGRESQL_USERNAME +CLOUDRON_POSTGRESQL_PASSWORD +CLOUDRON_POSTGRESQL_HOST +CLOUDRON_POSTGRESQL_PORT +CLOUDRON_POSTGRESQL_DATABASE +``` + +Options: + +- `locale` — Set `LC_LOCALE` and `LC_CTYPE` at database creation. + +Supported extensions: `btree_gist`, `btree_gin`, `citext`, `hstore`, `pgcrypto`, `pg_trgm`, `postgis`, `uuid-ossp`, `unaccent`, `vector`, `vectors`, and more. + +Debug: `PGPASSWORD=$CLOUDRON_POSTGRESQL_PASSWORD psql -h $CLOUDRON_POSTGRESQL_HOST -p $CLOUDRON_POSTGRESQL_PORT -U $CLOUDRON_POSTGRESQL_USERNAME -d $CLOUDRON_POSTGRESQL_DATABASE` + +## mongodb + +MongoDB 8.0. + +```text +CLOUDRON_MONGODB_URL +CLOUDRON_MONGODB_USERNAME +CLOUDRON_MONGODB_PASSWORD +CLOUDRON_MONGODB_HOST +CLOUDRON_MONGODB_PORT +CLOUDRON_MONGODB_DATABASE +CLOUDRON_MONGODB_OPLOG_URL # only when oplog enabled +``` + +Options: + +- `oplog: true` — Enable oplog access. + +## redis + +Redis 8.4. Data is persistent. + +```text +CLOUDRON_REDIS_URL +CLOUDRON_REDIS_HOST +CLOUDRON_REDIS_PORT +CLOUDRON_REDIS_PASSWORD +``` + +Options: + +- `noPassword: true` — Skip password auth (safe: Redis is only reachable on internal Docker network). + +## ldap + +LDAP v3 authentication. + +```text +CLOUDRON_LDAP_SERVER +CLOUDRON_LDAP_HOST +CLOUDRON_LDAP_PORT +CLOUDRON_LDAP_URL +CLOUDRON_LDAP_USERS_BASE_DN +CLOUDRON_LDAP_GROUPS_BASE_DN +CLOUDRON_LDAP_BIND_DN +CLOUDRON_LDAP_BIND_PASSWORD +``` + +Suggested filter: `(&(objectclass=user)(|(username=%uid)(mail=%uid)))` + +User attributes: `uid`, `cn`, `mail`, `displayName`, `givenName`, `sn`, `username`, `samaccountname`, `memberof` + +Group attributes: `cn`, `gidnumber`, `memberuid` + +Cannot be added to an existing app — reinstall required. + +## oidc + +OpenID Connect authentication. + +```text +CLOUDRON_OIDC_PROVIDER_NAME +CLOUDRON_OIDC_DISCOVERY_URL +CLOUDRON_OIDC_ISSUER +CLOUDRON_OIDC_AUTH_ENDPOINT +CLOUDRON_OIDC_TOKEN_ENDPOINT +CLOUDRON_OIDC_KEYS_ENDPOINT +CLOUDRON_OIDC_PROFILE_ENDPOINT +CLOUDRON_OIDC_CLIENT_ID +CLOUDRON_OIDC_CLIENT_SECRET +``` + +Options: + +- `loginRedirectUri` — Callback path (e.g. `/auth/openid/callback`). Multiple paths: comma-separated. +- `logoutRedirectUri` — Post-logout path. +- `tokenSignatureAlgorithm` — `RS256` (default) or `EdDSA`. + +## sendmail + +Outgoing email (SMTP relay). + +```text +CLOUDRON_MAIL_SMTP_SERVER +CLOUDRON_MAIL_SMTP_PORT # STARTTLS disabled on this port +CLOUDRON_MAIL_SMTPS_PORT +CLOUDRON_MAIL_SMTP_USERNAME +CLOUDRON_MAIL_SMTP_PASSWORD +CLOUDRON_MAIL_FROM +CLOUDRON_MAIL_FROM_DISPLAY_NAME # only when supportsDisplayName is set +CLOUDRON_MAIL_DOMAIN +``` + +Options: + +- `optional: true` — All env vars absent; app uses user-provided email config. +- `supportsDisplayName: true` — Enables `CLOUDRON_MAIL_FROM_DISPLAY_NAME`. +- `requiresValidCertificate: true` — Sets `CLOUDRON_MAIL_SMTP_SERVER` to FQDN. + +## recvmail + +Incoming email (IMAP/POP3). + +```text +CLOUDRON_MAIL_IMAP_SERVER +CLOUDRON_MAIL_IMAP_PORT +CLOUDRON_MAIL_IMAPS_PORT +CLOUDRON_MAIL_POP3_PORT +CLOUDRON_MAIL_POP3S_PORT +CLOUDRON_MAIL_IMAP_USERNAME +CLOUDRON_MAIL_IMAP_PASSWORD +CLOUDRON_MAIL_TO +CLOUDRON_MAIL_TO_DOMAIN +``` + +May be disabled if the server is not receiving email for the domain. Handle absent env vars. + +## email + +Full email capabilities (SMTP + IMAP + ManageSieve). For webmail applications. + +```text +CLOUDRON_EMAIL_SMTP_SERVER +CLOUDRON_EMAIL_SMTP_PORT +CLOUDRON_EMAIL_SMTPS_PORT +CLOUDRON_EMAIL_STARTTLS_PORT +CLOUDRON_EMAIL_IMAP_SERVER +CLOUDRON_EMAIL_IMAP_PORT +CLOUDRON_EMAIL_IMAPS_PORT +CLOUDRON_EMAIL_SIEVE_SERVER +CLOUDRON_EMAIL_SIEVE_PORT +CLOUDRON_EMAIL_DOMAIN +CLOUDRON_EMAIL_DOMAINS +CLOUDRON_EMAIL_SERVER_HOST +``` + +Accept self-signed certificates for internal IMAP/Sieve connections. + +## proxyauth + +Authentication wall in front of the app. Reserves `/login` and `/logout` routes. + +Options: + +- `path` — Restrict to a path (e.g. `/admin`). Prefix with `!` to exclude (e.g. `!/webhooks`). +- `basicAuth` — Enable HTTP Basic auth (bypasses 2FA). +- `supportsBearerAuth` — Forward `Bearer` tokens to the app. + +Cannot be added to an existing app — reinstall required. + +## scheduler + +Cron-like periodic tasks. + +```json +"scheduler": { + "task_name": { + "schedule": "*/5 * * * *", + "command": "/app/code/task.sh" + } +} +``` + +Commands run in the app's environment (same env vars, access to `/tmp` and `/run`). 30-minute grace period per task. + +## tls + +Certificate access for non-HTTP protocols. + +Files: `/etc/certs/tls_cert.pem`, `/etc/certs/tls_key.pem` (read-only). App restarts on certificate renewal. + +## turn + +STUN/TURN service. + +```text +CLOUDRON_TURN_SERVER +CLOUDRON_TURN_PORT +CLOUDRON_TURN_TLS_PORT +CLOUDRON_TURN_SECRET +``` + +## docker + +Create Docker containers (restricted). Only superadmins can install/exec apps with this addon. + +```text +CLOUDRON_DOCKER_HOST # tcp://: +``` + +Restrictions: bind mounts under `/app/data` only, created containers join `cloudron` network, containers removed on app uninstall. diff --git a/.agents/tools/deployment/cloudron-app-packaging-skill/manifest-ref.md b/.agents/tools/deployment/cloudron-app-packaging-skill/manifest-ref.md new file mode 100644 index 000000000..75c45dd75 --- /dev/null +++ b/.agents/tools/deployment/cloudron-app-packaging-skill/manifest-ref.md @@ -0,0 +1,81 @@ +# Manifest Reference + +Full field reference for `CloudronManifest.json`. See the [Cloudron docs](https://docs.cloudron.io/packaging/manifest/) for detailed examples. + +## Required fields + +| Field | Type | Description | +|-------|------|-------------| +| `manifestVersion` | integer | Always `2` | +| `version` | semver string | Package version (e.g. `"1.0.0"`) | +| `healthCheckPath` | URL path | Path returning 2xx when app is healthy (e.g. `"/"`) | +| `httpPort` | integer | HTTP port the app listens on (e.g. `8000`) | + +## Ports + +| Field | Type | Description | +|-------|------|-------------| +| `httpPort` | integer | Primary HTTP port | +| `httpPorts` | object | Additional HTTP services on secondary domains. Keys are env var names. Values: `{ title, description, containerPort, defaultValue }` | +| `tcpPorts` | object | Non-HTTP TCP ports. Keys are env var names. Values: `{ title, description, defaultValue, containerPort, portCount, readOnly, enabledByDefault }` | +| `udpPorts` | object | UDP ports. Same structure as `tcpPorts` | + +The `containerPort` is the port inside the container. `defaultValue` is the suggested external port shown during install. Disabled ports remove their env var at runtime — apps must handle this. + +## Addons + +| Field | Type | Description | +|-------|------|-------------| +| `addons` | object | Keys: `email`, `ldap`, `localstorage`, `mongodb`, `mysql`, `oidc`, `postgresql`, `proxyauth`, `recvmail`, `redis`, `sendmail`, `scheduler`, `tls`. Values are option objects (often `{}`) | + +## Metadata (for App Store / CloudronVersions.json) + +| Field | Type | Description | +|-------|------|-------------| +| `id` | reverse domain string | Unique app ID (e.g. `com.example.myapp`) | +| `title` | string | App name | +| `author` | string | Developer name and email | +| `tagline` | string | One-line description | +| `description` | markdown string | Detailed description. Supports `file://DESCRIPTION.md` | +| `changelog` | markdown string | Changes in this version. Supports `file://CHANGELOG` | +| `website` | URL | App website | +| `contactEmail` | email | Bug report / support email | +| `icon` | local file ref | Square 256x256 icon (e.g. `file://icon.png`) | +| `iconUrl` | URL | Remote icon URL | +| `tags` | string array | Filterable tags: `blog`, `chat`, `git`, `email`, `sync`, `gallery`, `notes`, `project`, `hosting`, `wiki` | +| `mediaLinks` | URL array | Screenshot URLs (3:1 aspect ratio, HTTPS) | +| `packagerName` | string | Name of package maintainer | +| `packagerUrl` | URL | Package maintainer URL | +| `documentationUrl` | URL | Link to app docs | +| `forumUrl` | URL | Link to support forum | +| `upstreamVersion` | string | Upstream app version (display only) | + +## Behavior + +| Field | Type | Description | +|-------|------|-------------| +| `memoryLimit` | integer (bytes) | Max RAM + swap (default 256 MB / `268435456`) | +| `multiDomain` | boolean | Allow alias domains. Sets `CLOUDRON_ALIAS_DOMAINS` env var | +| `optionalSso` | boolean | Allow install without user management. Auth addon env vars are absent when SSO is off | +| `configurePath` | URL path | Admin panel path shown in dashboard (e.g. `/wp-admin/`) | +| `logPaths` | string array | Log file paths when stdout is not possible | +| `capabilities` | string array | Extra Linux capabilities: `net_admin`, `mlock`, `ping`, `vaapi` | +| `runtimeDirs` | string array | Writable subdirs of `/app/code` (not backed up, not persisted across updates) | +| `persistentDirs` | string array | Writable dirs persisted across updates but not in filesystem backup. Use with `backupCommand`. Requires `minBoxVersion: 9.1.0` | +| `backupCommand` | string | Shell command run during backup to dump persistent data into `/app/data`. Requires `minBoxVersion: 9.1.0` | +| `restoreCommand` | string | Shell command run during restore to populate `persistentDirs` from `/app/data`. Requires `minBoxVersion: 9.1.0` | + +## Post-install + +| Field | Type | Description | +|-------|------|-------------| +| `postInstallMessage` | markdown string | Shown after install. Supports `file://POSTINSTALL.md`. Tags: `...`, `...`. Variables: `$CLOUDRON-APP-DOMAIN`, `$CLOUDRON-APP-FQDN`, `$CLOUDRON-APP-ORIGIN`, `$CLOUDRON-USERNAME`, `$CLOUDRON-APP-ID` | +| `checklist` | object | Post-install todo items. Keys are item IDs. Values: `{ message, sso }`. `sso: true` = shown only with auth, `sso: false` = shown only without auth | + +## Versioning + +| Field | Type | Description | +|-------|------|-------------| +| `minBoxVersion` | semver | Minimum platform version (default `0.0.1`) | +| `maxBoxVersion` | semver | Maximum platform version (rarely needed) | +| `targetBoxVersion` | semver | Platform version the app was tested on. Enables compatibility behavior for older apps | diff --git a/.agents/tools/deployment/cloudron-app-publishing-skill.md b/.agents/tools/deployment/cloudron-app-publishing-skill.md new file mode 100644 index 000000000..021cab8a8 --- /dev/null +++ b/.agents/tools/deployment/cloudron-app-publishing-skill.md @@ -0,0 +1,177 @@ +--- +description: "Distribute Cloudron apps via CloudronVersions.json version catalogs" +mode: subagent +imported_from: external +tools: + read: true + write: true + edit: true + bash: true + webfetch: true +--- + +# Cloudron App Publishing + +Distribute Cloudron apps independently using a `CloudronVersions.json` version catalog. Users add the file's URL in their dashboard or install via `cloudron install --versions-url `. + + + +## Quick Reference + +- **Purpose**: Publish and distribute Cloudron app packages outside the official App Store +- **Docs**: [docs.cloudron.io/packaging/publishing](https://docs.cloudron.io/packaging/publishing) +- **Upstream skill**: [git.cloudron.io/docs/skills](https://git.cloudron.io/docs/skills) (`cloudron-app-publishing`) +- **Prerequisite**: App must be built with `cloudron build` (local or build service) -- on-server builds cannot be published +- **Key file**: `CloudronVersions.json` -- version catalog hosted at a public URL +- **Install method**: Dashboard "Community apps" or `cloudron install --versions-url ` + + + +## Prerequisites + +The app must be built and pushed to a registry with `cloudron build`. On-server builds (`cloudron install` without `--image`) do not produce registry-hosted images and cannot be published. + +## Workflow + +```bash +cloudron versions init # create CloudronVersions.json, scaffold manifest +cloudron build # build and push image +cloudron versions add # add version to catalog +# host CloudronVersions.json at a public URL +``` + +## Initialize + +```bash +cloudron versions init +``` + +Creates `CloudronVersions.json` in the package directory. Also adds missing publishing fields to `CloudronManifest.json` with placeholder values and creates stub files: + +- `DESCRIPTION.md` -- detailed app description +- `CHANGELOG` -- version changelog +- `POSTINSTALL.md` -- post-install message shown to users + +Edit all placeholders and stubs before adding a version. + +### Required Manifest Fields for Publishing + +Beyond what `cloudron init` provides, publishing requires: + +| Field | Example | +|-------|---------| +| `id` | `com.example.myapp` | +| `title` | `My App` | +| `author` | `Jane Developer ` | +| `tagline` | `A short one-line description` | +| `version` | `1.0.0` | +| `website` | `https://example.com/myapp` | +| `contactEmail` | `support@example.com` | +| `iconUrl` | `https://example.com/icon.png` | +| `packagerName` | `Jane Developer` | +| `packagerUrl` | `https://example.com` | +| `tags` | `["productivity", "collaboration"]` | +| `mediaLinks` | `["https://example.com/screenshot.png"]` | +| `description` | `file://DESCRIPTION.md` | +| `changelog` | `file://CHANGELOG` | +| `postInstallMessage` | `file://POSTINSTALL.md` | +| `minBoxVersion` | `9.1.0` | + +`cloudron versions init` scaffolds all of these with defaults. + +## Build Commands + +### cloudron build + +Builds the Docker image. Behavior depends on whether a build service is configured: + +```bash +cloudron build # build (local or remote) +cloudron build --no-cache # rebuild without Docker cache +cloudron build --no-push # build but skip push +cloudron build -f Dockerfile.cloudron # use specific Dockerfile +cloudron build --build-arg KEY=VALUE # pass Docker build args +``` + +On first run, prompts for the Docker repository (e.g. `registry/username/myapp`). Remembers it for subsequent runs. + +### Other Build Subcommands + +| Command | Purpose | +|---------|---------| +| `cloudron build reset` | Clear saved repository, image, and build info | +| `cloudron build info` | Show current build config (image, repository, git commit) | +| `cloudron build login` | Authenticate with a remote build service | +| `cloudron build logout` | Log out from the build service | +| `cloudron build logs --id ` | Stream logs for a remote build | +| `cloudron build push --id ` | Push a remote build to a registry | +| `cloudron build status --id ` | Check status of a remote build | + +## Versions Commands + +### cloudron versions add + +Adds the current version to `CloudronVersions.json`. Reads the version from `CloudronManifest.json` and the last built Docker image. + +```bash +cloudron versions add +``` + +### cloudron versions list + +```bash +cloudron versions list +``` + +Shows all versions with their creation date, image, and publish state. + +### cloudron versions update + +Updates an existing version entry. Primarily used to change the publish state. + +```bash +cloudron versions update --version 1.0.0 --state published +``` + +Avoid changing the manifest or image of a published version -- users may have already installed it. To ship changes, revoke the existing version and add a new one. + +### cloudron versions revoke + +Marks the latest published version as revoked. Users who have not yet updated will not receive it. + +```bash +cloudron versions revoke +``` + +To ship a fix: bump the version in `CloudronManifest.json`, rebuild, run `cloudron versions add`. + +## Distribution + +Host `CloudronVersions.json` at any publicly accessible URL (static file host, git repo, web server). + +Users install in two ways: + +- **Dashboard** -- Add the URL under Community apps in the dashboard settings. Updates appear automatically. +- **CLI** -- `cloudron install --versions-url ` + +## Typical Release Cycle + +```bash +# 1. Edit code, bump version in CloudronManifest.json +# 2. Build and push +cloudron build + +# 3. Add to catalog +cloudron versions add + +# 4. Commit and push CloudronVersions.json to hosting +git add CloudronVersions.json && git commit -m "release 1.1.0" && git push +``` + +## Community Packages (9.1+) + +Community packages can be non-free (paid). The package publisher can keep Docker images private, and the end user sets up a [private Docker registry](https://docs.cloudron.io/docker#private-registry) to access the package. Automation of purchase/discovery is outside Cloudron's scope. + +## Forum + +Post about new packages in the [App Packaging & Development](https://forum.cloudron.io/category/96/app-packaging-development) category. diff --git a/.agents/tools/deployment/cloudron-server-ops-skill.md b/.agents/tools/deployment/cloudron-server-ops-skill.md new file mode 100644 index 000000000..44bfa0999 --- /dev/null +++ b/.agents/tools/deployment/cloudron-server-ops-skill.md @@ -0,0 +1,248 @@ +--- +description: "Manage apps on a Cloudron server using the cloudron CLI" +mode: subagent +imported_from: external +tools: + read: true + bash: true + webfetch: true +--- + +# Cloudron Server Operations + +The `cloudron` CLI manages apps on a Cloudron server. All commands operate on apps, not the server itself. + + + +## Quick Reference + +- **Purpose**: Manage installed Cloudron apps via CLI (logs, exec, backups, env vars, lifecycle) +- **Docs**: [docs.cloudron.io/packaging/cli](https://docs.cloudron.io/packaging/cli) +- **Upstream skill**: [git.cloudron.io/docs/skills](https://git.cloudron.io/docs/skills) (`cloudron-server-ops`) +- **Install CLI**: `sudo npm install -g cloudron` +- **Login**: `cloudron login my.example.com` (opens browser for auth; 9.1+ uses OIDC) +- **CI/CD**: Use `--server` and `--token` flags for non-interactive use +- **Also see**: `cloudron-helper.sh` for multi-server management via API + + + +## Setup + +```bash +sudo npm install -g cloudron # install on your PC/Mac, NOT on the server +cloudron login my.example.com # opens browser for authentication +``` + +Token is stored in `~/.cloudron.json`. + +For self-signed certificates: `cloudron login my.example.com --allow-selfsigned` + +### 9.1+ OIDC Login + +In Cloudron 9.1+, the CLI uses OIDC login (browser-based) to support passkey authentication. For automated pipelines, use a pre-obtained API token from the dashboard with `--token`. + +## App Targeting + +Most commands require `--app` to specify which app: + +```bash +cloudron logs --app blog.example.com # by FQDN +cloudron logs --app blog # by subdomain/location +cloudron logs --app 52aae895-5b7d-4625-8d4c-... # by app ID +``` + +When run from a directory with `CloudronManifest.json` and a previously installed app, the CLI auto-detects the app. + +## Commands + +### Listing and Inspection + +```bash +cloudron list # all installed apps +cloudron list -q # quiet (IDs only) +cloudron list --tag web # filter by tag +cloudron status --app # app details (status, domain, memory, image) +cloudron inspect # raw JSON of the Cloudron server +``` + +### App Lifecycle + +```bash +cloudron install # install app (on-server build or --image) +cloudron update --app # update app (rebuilds or uses --image) +cloudron uninstall --app +cloudron repair --app # reconfigure app without changing image +cloudron clone --app --location new-location +``` + +`cloudron install` and `cloudron update` accept: + +- `--image ` -- use a pre-built Docker image +- `--no-backup` -- skip backup before update +- `-l, --location ` -- set the app location +- `-s, --secondary-domains ` -- secondary domain bindings +- `-p, --port-bindings ` -- TCP/UDP port bindings +- `-m, --memory-limit ` -- override memory limit +- `--versions-url ` -- install a community app from a CloudronVersions.json URL + +### On-Server Build and Deploy (9.1+) + +```bash +# From a package directory with CloudronManifest.json + Dockerfile: +cloudron install --location myapp # uploads source, builds on server, installs +cloudron update --app myapp # uploads source, rebuilds, updates +``` + +Source is part of the app backup. On restore, the app rebuilds from the backed-up source. Requires Dockerfiles to be deterministic. + +### Run State + +```bash +cloudron start --app +cloudron stop --app +cloudron restart --app +cloudron cancel --app # cancel pending task +``` + +### Logs + +```bash +cloudron logs --app # recent logs +cloudron logs --app -f # follow (tail) +cloudron logs --app -l 200 # last 200 lines +cloudron logs --system # platform system logs +cloudron logs --system mail # specific system service +``` + +### Shell and Exec + +```bash +cloudron exec --app # interactive shell +cloudron exec --app -- ls -la /app/data # run a command +cloudron exec --app -- bash -c 'echo $CLOUDRON_MYSQL_URL' # with env vars +``` + +### Debug Mode + +When an app keeps crashing, `cloudron exec` may disconnect. Debug mode pauses the app (skips CMD) and makes the filesystem read-write: + +```bash +cloudron debug --app # enter debug mode +cloudron debug --app --disable # exit debug mode +``` + +### File Transfer + +```bash +cloudron push --app local.txt /tmp/remote.txt # push file +cloudron push --app localdir /tmp/ # push directory +cloudron pull --app /app/data/file.txt . # pull file +cloudron pull --app /app/data/ ./backup/ # pull directory +``` + +### Environment Variables + +```bash +cloudron env list --app +cloudron env get --app MY_VAR +cloudron env set --app MY_VAR=value OTHER=val2 # restarts app +cloudron env unset --app MY_VAR # restarts app +``` + +### Configuration + +```bash +cloudron set-location --app -l new-subdomain +cloudron set-location --app -s "api.example.com" # secondary domain +cloudron set-location --app -p "SSH_PORT=2222" # port binding +``` + +### Backups + +```bash +cloudron backup create --app # create backup +cloudron backup list --app # list backups +cloudron restore --app --backup # restore from backup +cloudron export --app # export to backup storage +cloudron import --app --backup-path /path # import external backup +``` + +Backup encryption utilities (local, offline): + +```bash +cloudron backup decrypt --password +cloudron backup decrypt-dir --password +cloudron backup encrypt --password +``` + +### Utilities + +```bash +cloudron open --app # open app in browser +cloudron init # create CloudronManifest.json + Dockerfile +cloudron completion # shell completion +``` + +## CI/CD Integration + +Use `--server` and `--token` to run commands non-interactively. Get API tokens from `https://my.example.com/#/profile`: + +```bash +cloudron update \ + --server my.example.com \ + --token \ + --app blog.example.com \ + --image username/image:tag +``` + +## Global Options + +| Option | Purpose | +|--------|---------| +| `--server ` | Target Cloudron server | +| `--token ` | API token (for CI/CD) | +| `--allow-selfsigned` | Accept self-signed TLS certificates | +| `--no-wait` | Do not wait for the operation to complete | + +## Common Workflows + +### Check and Restart a Misbehaving App + +```bash +cloudron status --app +cloudron logs --app -l 100 +cloudron restart --app +``` + +### Debug a Crashing App + +```bash +cloudron debug --app +cloudron exec --app +# inspect filesystem, check logs, test manually +cloudron debug --app --disable +``` + +### Backup and Restore + +```bash +cloudron backup create --app +cloudron backup list --app +# note the backup ID +cloudron restore --app --backup +``` + +### Install a Community Package (9.1+) + +```bash +# From a CloudronVersions.json URL +cloudron install --versions-url https://example.com/CloudronVersions.json --location myapp +``` + +### Set Env Vars for an App + +```bash +cloudron env set --app FEATURE_FLAG=true DEBUG=1 +# app restarts automatically +cloudron logs --app -f +```