Skip to content

refactor: deduplicate addon env vars — single source of truth in addons-ref.md #2652

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 1 commit into from
Mar 1, 2026
Merged

refactor: deduplicate addon env vars — single source of truth in addons-ref.md #2652

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
71 changes: 6 additions & 65 deletions .agents/tools/deployment/cloudron-app-packaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ Need web terminal access or complex deps?
| Cron jobs | `scheduler` | (config in manifest) |
| TLS certs | `tls` | `/etc/certs/tls_*.pem` |

**Note**: `localstorage` is MANDATORY for all apps that need persistent data.
**Note**: `localstorage` is MANDATORY for all apps that need persistent data. For full env var lists and addon options, see [addons-ref.md](cloudron-app-packaging-skill/addons-ref.md).

### Process Model Selection

Expand Down Expand Up @@ -340,7 +340,7 @@ fastcgi_temp_path /run/nginx/fastcgi;
server {
listen 8000; # Internal port, never 80/443
root /app/code/public;

location / {
try_files $uri $uri/ /index.php?$query_string;
}
Expand Down Expand Up @@ -491,73 +491,14 @@ exec /usr/bin/supervisord --configuration /app/code/supervisord.conf

## Addon Environment Variables

### PostgreSQL

```bash
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

```bash
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

```bash
CLOUDRON_REDIS_URL=redis://:password@host:6379
CLOUDRON_REDIS_HOST=redis
CLOUDRON_REDIS_PORT=6379
CLOUDRON_REDIS_PASSWORD=password
```

**Note**: Cloudron Redis REQUIRES authentication.
For the full environment variable reference for all addons (mysql, postgresql, mongodb, redis, ldap, oidc, sendmail, recvmail, email, proxyauth, scheduler, tls, turn, docker) including addon-specific options, see [addons-ref.md](cloudron-app-packaging-skill/addons-ref.md).
Copy link

@gemini-code-assist gemini-code-assist bot Mar 1, 2026

Choose a reason for hiding this comment

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

medium

For better readability, it would be helpful to format the list of addon names as code spans using backticks. This makes them stand out from the surrounding text and is a common convention for technical terms.

Suggested change
For the full environment variable reference for all addons (mysql, postgresql, mongodb, redis, ldap, oidc, sendmail, recvmail, email, proxyauth, scheduler, tls, turn, docker) including addon-specific options, see [addons-ref.md](cloudron-app-packaging-skill/addons-ref.md).
For the full environment variable reference for all addons (`mysql`, `postgresql`, `mongodb`, `redis`, `ldap`, `oidc`, `sendmail`, `recvmail`, `email`, `proxyauth`, `scheduler`, `tls`, `turn`, `docker`) including addon-specific options, see [addons-ref.md](cloudron-app-packaging-skill/addons-ref.md).


### Sendmail (SMTP)

```bash
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
```

### LDAP

```bash
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
```

### OIDC (OAuth)

```bash
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
```
**Key pattern**: Read env vars at runtime on every start — values can change across restarts. Run DB migrations on each start.
Copy link

@gemini-code-assist gemini-code-assist bot Mar 1, 2026

Choose a reason for hiding this comment

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

medium

The "Key pattern" line contains two distinct but important pieces of advice. To improve clarity and make them easier to digest, consider presenting them as a bulleted list. This aligns with the guideline to format important operational details as bullet points for clarity and readability.

Suggested change
**Key pattern**: Read env vars at runtime on every start — values can change across restarts. Run DB migrations on each start.
**Key patterns**:
* Read env vars at runtime on every start — values can change across restarts.
* Run DB migrations on each start.
References
  1. For important operational details like task claiming, format them as bullet points for clarity and readability.


### General Variables (Always Available)

These are always set, regardless of which addons are declared:

```bash
CLOUDRON_APP_ORIGIN=https://app.domain.com # Full URL with protocol
CLOUDRON_APP_DOMAIN=app.domain.com # Domain only
Expand Down
Loading