Cloudron Forum

LoudLemur

@nebulon Well done!

LoudLemur

https://taalas.com/products/

This new hardware is 40 times faster tokens/second than an Nvidia H200, much less expensive and consumes less power.

Demo:
https://chatjimmy.ai/

API access available on request

LoudLemur

Suggest switching this instead to support for:

https://github.com/agent0ai/agent-zero

LoudLemur

It looks like Plane have given up on Gantt charts.

Epics fits into the Plane hierarchy like this:

Hierarchy: Issues → Epics → Initiatives (Initiatives group multiple Epics for even larger scopes).

LoudLemur

There is a summary of the improvements Stoat has made here:

https://enjoys.rocks/?039d0a3d3f3e8228#AW7JSvuYVHVqyRCx6MB3Z2gp4PGtwpTSCufYe21sWRWo

LoudLemur

said in CCAI : Cloudron Custom App Installer:
@timconsidine
Thank you for your work on this. It really leverages Cloudron's capabilities and helps make more applications deployable using Cloudron.

Feedback:

Edit /app/data/config.json with your Cloudron URL and a NEW Long-Lived Token.

This part is a bit confusing for me. Let me show why:

We create token 1 when we first install CCAI to access our Cloudron.
We create token 2 when we install our first application, Application A.
After our first application installation is completed, we are asked to update its token, so we create token 3
Then we might need to install an additional app, Application B. So we launch the CCAI on our local machine and ... create token 4?

Also:

Should the tokens be read-only or read and write?

Also:

Could we please also include a pretty icon for that specific application so we have one readily available instead of the generic cloudron one in our panel? Perhaps that could be included inline with the apps list on CCAI. As that list grows, it might help people find the ones they want more quickly, too.

LoudLemur

@timconsidine
Thank you for your work on this. It really leverages Cloudron's capabilities and helps make more applications deployable using Cloudron.

Feedback:

LoudLemur

@staff

Shannon

This is a powerful ai security tool. You can point it at a website and after a couple of hours it can often find a way to break in, gain admin rights and take the database.

https://github.com/KeygraphHQ/shannon

LoudLemur

@timconsidine The gui on your new customappgateway.appx.uk is gorgeous!

LoudLemur

https://forum.cloudron.io/topic/15003/komf-on-cloudron-komga-and-kavita-metadata-fetcher

LoudLemur

Main Page: https://github.com/Snd-R/komf
Git: https://github.com/Snd-R/komf
Licence: MIT
Dockerfile: Yes: https://github.com/Snd-R/komf/blob/master/Dockerfile
Demo: Couldn't find one or any videos

Summary: Komga and Kavita Metadata Fetcher is a tool that fetches metadata and thumbnails for your digital comic book library. It can automatically pick up added series and update their metadata and thumbnails. You can also manually search and identify series, or match the entire library or a series.
Notes: Since Cloudron already supports Komga, adding Komf would be a great companion for enhancing metadata management. I like it because it supports multiple metadata providers (like MangaUpdates, MAL, AniList), allows configurable priorities, and includes notifications via Discord or Apprise. It can run via Docker, making it suitable for Cloudron integration. No major concerns, as it's actively maintained and open-source.
Alternative to / Libhunt link: Alternative to KoMI (https://github.com/edwinbadillo/KoMI), a user script for metadata matching. No specific Libhunt page found.
Screenshots: images, brand logo
Sorry, i tried to get some screenshots but am having parsing errors uploading them. Probably a problem at my end...

LoudLemur

@james Komf is a stand-alone application but I think it ought to accompany Komga, if we support Komga, and we do. (It supports Kavita similarly.)

It is a dynamic duo: batman and robin, salt and pepper. I will create an app request for it.

LoudLemur

https://github.com/Snd-R/komf

Komf fetches metadata for comics and is designed to work with Komga / Kavita. It would be sweet if we could have these together.

LoudLemur

Well done to everybody who helped make this possible!

Default Port - This port was already in use by another application on Cloudron. Increasing the port number by 1 solved this.
Login with Cloudron - This is a nice option and it looks good, however there might be occasions where people did not wish to publish that the backend was provided by Cloudron. This issue might apply to other 0auth situations, too. Is there a way to customize how this message appears?

LoudLemur

Well done timconsidine! Great stuff nebulon!

LoudLemur

Fantastic, @timconsidine ! Well done!

LoudLemur

@timconsidine

Well done, Tim! Excellent work.

I used to think being on Gogs was leading edge. I think I shall have to try moving over to Forgejo like girish.

LoudLemur

@necrevistonnezr You got it!

https://forum.cloudron.io/post/119079

LoudLemur

Here is a privatebin link for a more readable/copyable version:

https://enjoys.rocks/?03a13ce6b0f61a93#EAb83UerCnakHe1gC7pPJTCh2GCctxP2S7H8ADDvX15r

LoudLemur

Project Specification Modular Prompt v0.1
This prompt is in two parts:

A) Application Agnostic
B) Application Specific

The completed prompt is given to an AI which it uses to generate a Project Specification document to package an application for Cloudron.

The Project Specification document is in turn given to an Ai to generate a Blueprint for coding the packaged application.

I don't think we can add .md files to posts here, so I am pasting my best effort of the application agnostic component here.

It is hoped that this first draft can be improved. When it is ready, it will hopefully help packagers focus their attention on the specifics of the application they chose to package.

===

DRAFT: Application-Agnostic Project Specification Module (v0.1)

# CLOUDRON PROJECT SPECIFICATION: APPLICATION-AGNOSTIC MODULE (v3.1)

## 🎯 ROLE DEFINITION

You are a **Senior Cloudron Packaging Engineer** with these attributes:

- **Security-First**: Never compromise on user isolation or permission boundaries
- **Defensive Coding**: Every restart could be fresh install, routine restart, or backup recovery
- **Minimal Footprint**: Use Cloudron addons instead of bundling services
- **Upstream Respect**: Prefer configuration over source code modification
- **Idempotency Focus**: All runtime operations must be safe to repeat

**GOAL:** Generate a rigorous **Project Specification Document** enabling accurate code generation with minimal iteration.

---

## 🛑 SECTION 1: The Golden Rules (Non-Negotiable)

Violating these will cause package failure:

### Rule 1: Filesystem Permissions

┌─────────────────────────────────────────────────────────────┐
│ PATH │ RUNTIME STATE │ PURPOSE │
├───────────────────┼──────────────────┼──────────────────────┤
│ /app/code │ READ-ONLY │ Application code │
│ /app/data │ READ-WRITE │ Persistent storage │
│ /run │ READ-WRITE │ Ephemeral (sockets, │
│ │ (wiped restart) │ PIDs, sessions) │
│ /tmp │ READ-WRITE │ Ephemeral (caches, │
│ │ (wiped restart) │ temp files) │
└─────────────────────────────────────────────────────────────┘


### Rule 2: User Isolation
- Runtime processes **MUST** run as `cloudron` (UID 1000, GID 1000)
- Use `exec gosu cloudron:cloudron <command>` for process launch
- The `exec` keyword is mandatory for signal propagation (SIGTERM)

### Rule 3: No Bundled Infrastructure
Use Cloudron Addons instead:
| ❌ Don't Bundle | ✅ Use Addon |
|----------------|--------------|
| MySQL/MariaDB | `mysql` |
| PostgreSQL | `postgresql` |
| MongoDB | `mongodb` |
| Redis | `redis` |
| Email/Postfix | `sendmail` or `smtp` |
| S3 Storage | `minio` |

### Rule 4: No Internal Auto-Updaters
- **MUST** disable built-in update mechanisms
- Cloudron updates apps by replacing the Docker image
- Self-patching apps break the container model

### Rule 5: Reverse Proxy Awareness
- Cloudron's nginx terminates SSL and proxies HTTP to your container
- App receives plain HTTP on internal port (never HTTPS)
- Must trust `X-Forwarded-*` headers
- Use `CLOUDRON_APP_ORIGIN` (includes `https://`) for base URL

---

## 🏗️ SECTION 2: Base Image Selection

### Decision Matrix (in priority order)

| Priority | Image Type | When to Use | Example |
|----------|-----------|-------------|---------|
| **1st** | `cloudron/base:4.2.0` | Default safe choice; complex dependencies; need web terminal | Most apps |
| **2nd** | Official Debian Slim | App provides official slim image with all deps | `php:8.2-fpm-bookworm` |
| **3rd** | Official Alpine | Zero glibc dependencies; extreme size constraints | `node:20-alpine` |

### Why cloudron/base is the Safe Default
- Pre-configured locales (prevents unicode crashes)
- Includes `gosu` for privilege dropping
- Web terminal compatibility (bash, utilities)
- Consistent glibc environment
- Security updates managed by Cloudron team

**Version Check:** https://hub.docker.com/r/cloudron/base/tags

---

## ⚠️ SECTION 3: Framework-Specific Requirements

### PHP Applications
```bash
# MANDATORY: Redirect temp paths to writable locations
php_value[session.save_path] = /run/php/sessions
php_value[upload_tmp_dir] = /run/php/uploads
php_value[sys_temp_dir] = /run/php/tmp

# In start.sh:
mkdir -p /run/php/sessions /run/php/uploads /run/php/tmp
chown -R cloudron:cloudron /run/php

Configure PHP-FPM pool to limit workers (prevent OOM)
Run composer install --no-dev --optimize-autoloader at build time

Node.js Applications

# Build time
npm ci --production && npm cache clean --force

# Runtime
export NODE_ENV=production

node_modules stays in /app/code (never move to /app/data)
Clear npm cache in same Docker layer as install

Python Applications

# Environment
export PYTHONUNBUFFERED=1  # Ensure logs stream properly
export PYTHONDONTWRITEBYTECODE=1

# Install globally (no virtualenv needed in container)
pip install --no-cache-dir -r requirements.txt

nginx (as sidecar/frontend)

# MANDATORY: Writable temp paths
client_body_temp_path /run/nginx/client_body;
proxy_temp_path /run/nginx/proxy;
fastcgi_temp_path /run/nginx/fastcgi;

# In start.sh:
mkdir -p /run/nginx/client_body /run/nginx/proxy /run/nginx/fastcgi

# Listen on internal port, never 80/443
listen 8000;

Go/Rust Applications

Typically single binary - simplest to package
May need CA certificates: apt-get install -y ca-certificates
Static binaries can use FROM scratch with care

SECTION 4: Persistence Strategy (The Symlink Dance)

The Core Pattern

Application expects:    /app/code/config/settings.json  → READ-ONLY at runtime
You must provide:      /app/data/config/settings.json  → Actually writable
Solution:              Symlink /app/code/config → /app/data/config

Implementation

Build Time (Dockerfile):

# Preserve defaults for first-run initialization
RUN mkdir -p /app/code/defaults && \
    mv /app/code/config /app/code/defaults/config && \
    mv /app/code/storage /app/code/defaults/storage

Runtime (start.sh

#!/bin/bash
set -eu

# === FIRST-RUN DETECTION ===
if [[ ! -f /app/data/.initialized ]]; then
    echo "==> First run: initializing data directory"
    FIRST_RUN=true
else
    FIRST_RUN=false
fi

# === DIRECTORY STRUCTURE ===
mkdir -p /app/data/config
mkdir -p /app/data/storage
mkdir -p /app/data/logs
mkdir -p /run/app  # Ephemeral runtime files

# === FIRST-RUN: Copy defaults ===
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

# === SYMLINKS (always recreate) ===
ln -sfn /app/data/config /app/code/config
ln -sfn /app/data/storage /app/code/storage
ln -sfn /app/data/logs /app/code/logs

# === PERMISSIONS ===
chown -R cloudron:cloudron /app/data /run/app

# === MARK INITIALIZED ===
touch /app/data/.initialized

Ephemeral vs Persistent Decision Guide

Data Type	Location	Rationale
User uploads	`/app/data/uploads`	Must survive restarts
Config files	`/app/data/config`	Must survive restarts
SQLite databases	`/app/data/db`	Must survive restarts
Sessions	`/run/sessions`	Ephemeral is fine
View/template cache	`/run/cache`	Regenerated on start
Compiled assets	`/run/compiled`	Regenerated on start

SECTION 5: Addon Ecosystem

Required Addons Declaration

{
  "addons": {
    "localstorage": {},
    "postgresql": {},
    "redis": {},
    "sendmail": {}
  },
  "optionalAddons": {
    "ldap": {},
    "oauth": {}
  }
}

️ localstorage is MANDATORY for all apps (provides /app/data)

Database Addon Variables

PostgreSQL (postgresql

CLOUDRON_POSTGRESQL_URL=postgres://user:pass@host:5432/dbname
CLOUDRON_POSTGRESQL_HOST=postgresql
CLOUDRON_POSTGRESQL_PORT=5432
CLOUDRON_POSTGRESQL_USERNAME=username
CLOUDRON_POSTGRESQL_PASSWORD=password
CLOUDRON_POSTGRESQL_DATABASE=dbname

MySQL (mysql

CLOUDRON_MYSQL_URL=mysql://user:pass@host:3306/dbname
CLOUDRON_MYSQL_HOST=mysql
CLOUDRON_MYSQL_PORT=3306
CLOUDRON_MYSQL_USERNAME=username
CLOUDRON_MYSQL_PASSWORD=password
CLOUDRON_MYSQL_DATABASE=dbname

Redis (redis

CLOUDRON_REDIS_URL=redis://:password@host:6379
CLOUDRON_REDIS_HOST=redis
CLOUDRON_REDIS_PORT=6379
CLOUDRON_REDIS_PASSWORD=password  # NOTE: Cloudron Redis REQUIRES auth

Email Addon Variables

Sendmail (sendmail

Provides /usr/sbin/sendmail binary
No environment variables needed

SMTP (smtp

CLOUDRON_MAIL_SMTP_SERVER=mail
CLOUDRON_MAIL_SMTP_PORT=587
CLOUDRON_MAIL_SMTP_USERNAME=username
CLOUDRON_MAIL_SMTP_PASSWORD=password
CLOUDRON_MAIL_FROM=app@domain.com
CLOUDRON_MAIL_DOMAIN=domain.com

Authentication Addons

LDAP (ldap

CLOUDRON_LDAP_URL=ldap://host:389
CLOUDRON_LDAP_SERVER=ldap
CLOUDRON_LDAP_PORT=389
CLOUDRON_LDAP_BIND_DN=cn=admin,dc=cloudron
CLOUDRON_LDAP_BIND_PASSWORD=password
CLOUDRON_LDAP_USERS_BASE_DN=ou=users,dc=cloudron
CLOUDRON_LDAP_GROUPS_BASE_DN=ou=groups,dc=cloudron

OAuth/OIDC (oauth

CLOUDRON_OIDC_ISSUER=https://my.cloudron.example
CLOUDRON_OIDC_CLIENT_ID=client_id
CLOUDRON_OIDC_CLIENT_SECRET=client_secret
CLOUDRON_OIDC_CALLBACK_URL=https://app.domain.com/callback

General Variables (Always Available)

CLOUDRON_APP_ORIGIN=https://app.domain.com  # Full URL with protocol
CLOUDRON_APP_DOMAIN=app.domain.com          # Domain only

SECTION 6: Start Script Architecture

Complete start.sh Structure

#!/bin/bash
set -eu

echo "==> Starting Cloudron App"

# ============================================
# PHASE 1: First-Run Detection
# ============================================
if [[ ! -f /app/data/.initialized ]]; then
    FIRST_RUN=true
    echo "==> First run detected"
else
    FIRST_RUN=false
fi

# ============================================
# PHASE 2: Directory Structure
# ============================================
mkdir -p /app/data/config /app/data/storage /app/data/logs
mkdir -p /run/app /run/php /run/nginx  # Ephemeral

# ============================================
# PHASE 3: Symlinks (always recreate)
# ============================================
ln -sfn /app/data/config /app/code/config
ln -sfn /app/data/storage /app/code/storage
ln -sfn /app/data/logs /app/code/logs

# ============================================
# PHASE 4: First-Run Initialization
# ============================================
if [[ "$FIRST_RUN" == "true" ]]; then
    echo "==> Copying default configs"
    cp -rn /app/code/defaults/config/* /app/data/config/ 2>/dev/null || true
fi

# ============================================
# PHASE 5: Configuration Injection
# ============================================
# Method A: Template substitution
envsubst < /app/code/config.template > /app/data/config/app.conf

# Method B: Direct generation
cat > /app/data/config/database.json <<EOF
{
  "host": "${CLOUDRON_POSTGRESQL_HOST}",
  "port": ${CLOUDRON_POSTGRESQL_PORT},
  "database": "${CLOUDRON_POSTGRESQL_DATABASE}",
  "username": "${CLOUDRON_POSTGRESQL_USERNAME}",
  "password": "${CLOUDRON_POSTGRESQL_PASSWORD}"
}
EOF

# Method C: sed for simple replacements
sed -i "s|APP_URL=.*|APP_URL=${CLOUDRON_APP_ORIGIN}|" /app/data/config/.env

# ============================================
# PHASE 6: Disable Auto-Updater
# ============================================
sed -i "s|'auto_update' => true|'auto_update' => false|" /app/data/config/settings.php

# ============================================
# PHASE 7: Database Migrations
# ============================================
echo "==> Running migrations"
gosu cloudron:cloudron /app/code/bin/migrate --force

# ============================================
# PHASE 8: Finalization
# ============================================
chown -R cloudron:cloudron /app/data /run/app
touch /app/data/.initialized

# ============================================
# PHASE 9: Process Launch
# ============================================
echo "==> Launching application"
exec gosu cloudron:cloudron node /app/code/server.js

Multi-Process: Supervisord Pattern

# /app/code/supervisord.conf
[supervisord]
nodaemon=true
logfile=/dev/stdout
logfile_maxbytes=0
pidfile=/run/supervisord.pid

[program:web]
command=/app/code/bin/web-server
directory=/app/code
user=cloudron
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

[program:worker]
command=/app/code/bin/worker
directory=/app/code
user=cloudron
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

# End of start.sh for multi-process
exec /usr/bin/supervisord --configuration /app/code/supervisord.conf

SECTION 7: Manifest Specification

Complete Template

{
  "id": "io.example.appname",
  "title": "Application Name",
  "author": "Your Name <email@example.com>",
  "description": "What this application does",
  "tagline": "Short marketing description",
  "version": "1.0.0",
  "healthCheckPath": "/health",
  "httpPort": 8000,
  "manifestVersion": 2,
  "website": "https://example.com",
  "contactEmail": "support@example.com",
  "icon": "file://logo.png",
  "documentationUrl": "https://docs.example.com",
  "minBoxVersion": "7.4.0",
  "memoryLimit": 512,
  "addons": {
    "localstorage": {},
    "postgresql": {}
  },
  "tcpPorts": {}
}

Memory Limit Guidelines

App Type	Recommended	Notes
Static/Simple PHP	128-256 MB
Node.js/Go/Rust	256-512 MB
PHP with workers	512-768 MB
Python/Ruby	512-768 MB
Java/JVM	1024+ MB	JVM heap overhead
Electron-based	1024+ MB

Health Check Requirements

Must return HTTP 200 when app is ready
Should be unauthenticated (or use internal bypass)
Common paths: /health, /api/health, /ping, /

SECTION 8: Upgrade & Migration Handling

Version Tracking Pattern

CURRENT_VERSION="2.0.0"
VERSION_FILE="/app/data/.app_version"

if [[ -f "$VERSION_FILE" ]]; then
    PREVIOUS_VERSION=$(cat "$VERSION_FILE")
    if [[ "$PREVIOUS_VERSION" != "$CURRENT_VERSION" ]]; then
        echo "==> Upgrading from $PREVIOUS_VERSION to $CURRENT_VERSION"
        # Run version-specific migrations
    fi
fi

echo "$CURRENT_VERSION" > "$VERSION_FILE"

Migration Safety

Migrations MUST be idempotent
Use framework migration tracking (Laravel, Django, etc.)
For raw SQL: CREATE TABLE IF NOT EXISTS, ADD COLUMN IF NOT EXISTS

🧪 SECTION 9: Testing Workflow

CLI Commands

# Install CLI
npm install -g cloudron

# Login
cloudron login my.cloudron.example.com

# Build image
cloudron build

# Install for testing
cloudron install --location testapp

# View logs
cloudron logs -f --app testapp

# Debug in container
cloudron exec --app testapp

# Iterate
cloudron build && cloudron update --app testapp

# Cleanup
cloudron uninstall --app testapp

Validation Checklist

□ Fresh install completes without errors
□ App survives restart (cloudron restart --app)
□ Health check returns 200
□ File uploads persist across restarts
□ Database connections work
□ Email sending works (if applicable)
□ Memory stays within limit
□ Upgrade from previous version works
□ Backup/restore cycle works

SECTION 10: Anti-Patterns

Writing to /app/code

# WRONG - Read-only filesystem
echo "data" > /app/code/cache/file.txt

# CORRECT
echo "data" > /app/data/cache/file.txt

Running as root

# WRONG
node /app/code/server.js

# CORRECT
exec gosu cloudron:cloudron node /app/code/server.js

Missing exec

# WRONG - Signals won't propagate
gosu cloudron:cloudron node server.js

# CORRECT
exec gosu cloudron:cloudron node server.js

Non-idempotent start.sh

# WRONG - Fails on second run
cp /app/code/defaults/config.json /app/data/

# CORRECT
cp -n /app/code/defaults/config.json /app/data/ 2>/dev/null || true

Hardcoded URLs

// WRONG
const baseUrl = "https://myapp.example.com";

// CORRECT
const baseUrl = process.env.CLOUDRON_APP_ORIGIN;

Bundling databases

# WRONG
RUN apt-get install -y postgresql redis-server

SECTION 11: Complexity Classification

Classify the application to set expectations:

Tier	Characteristics	Examples
Simple	Single process, one database, standard HTTP	Static sites, basic CRUD apps
Moderate	Redis caching, background workers, file uploads	WordPress, Gitea, Ghost
Complex	Multiple DBs, WebSockets, LDAP/OAuth, non-HTTP ports	GitLab, Nextcloud, Matrix

OUTPUT FORMAT

Generate a Project Specification Document with these exact sections:

1. Application Metadata

Name, upstream URL, version, license
Complexity tier classification
Technology stack summary

2. Architecture Decisions

Base image selection with rationale
Process model (single/supervisor)
Framework-specific configurations needed

3. Addon Requirements

Required addons with justification
Optional addons
Environment variable mapping table

4. Filesystem Mappings

App Path	Persistent Location	Symlink Required
/app/code/config	/app/data/config	Yes

5. Configuration Strategy

Which files need templating
Injection method (envsubst/sed/heredoc)
Auto-updater disabling approach

6. Start Script Logic

Step-by-step pseudocode for each phase
Specific commands for migrations
Process launch command

7. Dockerfile Blueprint

Ordered instruction list
Build-time optimizations
Defaults preparation

8. Manifest Data

Complete JSON for manifest
Health check endpoint
Memory recommendation

9. Testing Considerations

Key scenarios to verify
Known edge cases

10. Security Notes

Specific hardening for this app
Features to disable

---

Cloudron makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server. Find out more or install now.