Addons

Overview

Addons are services — database, authentication, email, caching — that are part of the runtime. The platform handles setup, provisioning, scaling, and maintenance of addons.

Addons allow sharing services across applications. For example, a single MySQL server instance can serve multiple apps. Each app's addon access is isolated from other apps.

Using addons

Addons are opt-in and must be specified in the Manifest. When the app runs, environment variables contain the necessary information to access the addon. For example, the MySQL addon sets the CLOUDRON_MYSQL_URL environment variable — the connection string for the database.

Keep the following in mind when working with addons:

Environment variables are subject to change every time the app restarts. Restarts occur when the server reboots, a backup is restored, the app crashes, or an addon is re-provisioned. Do not cache environment variable values across restarts. Read them directly at runtime. For example, use process.env.CLOUDRON_MYSQL_URL (nodejs) or getenv("CLOUDRON_MYSQL_URL") (PHP).
Set up or update addons on each application start. Most applications use DB migration frameworks to manage the schema.
Configure addons in the addons section of the manifest:

    {
      ...
      "addons": {
        "ldap": { },
        "redis" : { }
      }
    }

Addons

Docker

This addon provides the ability to create Docker containers on behalf of the user. For security, only a limited set of Docker operations are permitted.

Exported environment variables:

CLOUDRON_DOCKER_HOST=        # tcp://<IP>:<port>

Key restrictions:

Only the app can access the Docker API. Containers created by the app cannot use the Docker API.
Created containers are automatically moved to the cloudron internal network.
Bind mounts must be under /app/data.
Containers created by an application are tracked and removed when the app is uninstalled.
Only a superadmin can install, update, or exec into apps with the Docker addon.

Email

This addon provides full email send and receive capabilities for webmail applications.

To send mail (e.g., notifications), use the sendmail addon. To receive email (e.g., user replies to notifications), use the recvmail addon instead.

Apps using the IMAP and ManageSieve services below must accept self-signed certificates. These addresses are internal to the server.

Exported environment variables:

CLOUDRON_EMAIL_SMTP_SERVER=       # SMTP server IP or hostname. This is the internal name of the mail server.
CLOUDRON_EMAIL_SMTP_PORT=         # SMTP server port. STARTL TLS is disabled on this port.
CLOUDRON_EMAIL_SMTPS_PORT=        # SMTPS server port
CLOUDRON_EMAIL_STARTTLS_PORT=     # SMTP STARTTLS port
CLOUDRON_EMAIL_IMAP_SERVER=       # IMAP server IP or hostname.
CLOUDRON_EMAIL_IMAP_PORT=         # IMAP server port
CLOUDRON_EMAIL_IMAPS_PORT=        # IMAPS server port. TLS required.
CLOUDRON_EMAIL_SIEVE_SERVER=      # ManageSieve server IP or hostname.
CLOUDRON_EMAIL_SIEVE_PORT=        # ManageSieve server port. TLS required.
CLOUDRON_EMAIL_DOMAIN=            # Primary mail domain of the app
CLOUDRON_EMAIL_DOMAINS=           # Comma separate list of domains handled by the server
CLOUDRON_EMAIL_SERVER_HOST=       # The FQDN of the mail server. Only use this, if the app cannot connect using the internal name.

LDAP

This addon provides LDAP based authentication via LDAP version 3.

Exported environment variables:

CLOUDRON_LDAP_SERVER=                                # ldap server IP
CLOUDRON_LDAP_HOST=                                  # ldap server IP (same as above)
CLOUDRON_LDAP_PORT=                                  # ldap server port
CLOUDRON_LDAP_URL=                                   # ldap url of the form ldap://ip:port
CLOUDRON_LDAP_USERS_BASE_DN=                         # ldap users base dn of the form ou=users,dc=cloudron
CLOUDRON_LDAP_GROUPS_BASE_DN=                        # ldap groups base dn of the form ou=groups,dc=cloudron
CLOUDRON_LDAP_BIND_DN=                               # DN to perform LDAP requests
CLOUDRON_LDAP_BIND_PASSWORD=                         # Password to perform LDAP requests

The suggested LDAP filter is (&(objectclass=user)(|(username=%uid)(mail=%uid))). This allows the user to login via username or email.

To debug, use cloudron exec to run the ldapsearch client within the app context:

cloudron exec

# List users
> ldapsearch -x -H "${CLOUDRON_LDAP_URL}" -D "${CLOUDRON_LDAP_BIND_DN}" -w "${CLOUDRON_LDAP_BIND_PASSWORD}" -b "${CLOUDRON_LDAP_USERS_BASE_DN}"

# List users with authentication (substitute username and password below)
> ldapsearch -x -H "${CLOUDRON_LDAP_URL}" -D cn=<username>,${CLOUDRON_LDAP_USERS_BASE_DN} -w <password> -b  "${CLOUDRON_LDAP_USERS_BASE_DN}"

# List groups
> ldapsearch -x -H "${CLOUDRON_LDAP_URL}" -D "${CLOUDRON_LDAP_BIND_DN}" -w "${CLOUDRON_LDAP_BIND_PASSWORD}" -b "${CLOUDRON_LDAP_GROUPS_BASE_DN}"

The user listing has the following LDAP attributes:

objectclass - array that contains user
objectcategory - set to 'person',
uid, entryuuid - Unique identifier
cn - Unique identifier (same as uid)
mail - User's primary email
displayName - Full name of the user
mailAlternateAddress - Alternate/Fallback email address of the user (for password reset)
givenName - First name of the user
sn - Last name of the user
username - Username set during account creation
samaccountname - Same as username
memberof - List of groups the user is a member of

The groups listing has the following LDAP attributes:

objectclass - array that contains group
cn: name of the group
gidnumber: Unique identifier
memberuid: array of members. Each entry here maps to uid in the user listing.

The LDAP addon cannot be enabled on already installed apps. Pushing an update with the LDAP addon enabled does not add LDAP functionality to existing installations. Install the app afresh for LDAP integration.

A "sso" flag tracks whether the app was installed with or without user management. This flag cannot be changed after installation. Allowing dynamic changes creates unclear scenarios — for example, what should happen to existing users when an app removes the LDAP addon? Some apps require explicit admin user creation as they don't support LDAP and local database authentication simultaneously.

Localstorage

All apps run within a read-only filesystem. This addon provides a writeable folder under /app/data/. All contents in this folder are included in backups. On first run, this folder is empty. Files added to this path as part of the app's image (Dockerfile) won't be present. Create the directory structure required by the app in the startup script.

File permissions and ownership within this directory are not preserved across restarts. Restore permissions in the startup script.

For apps running under the recommended cloudron user:

chown -R cloudron:cloudron /app/data

FTP

Enable FTP access with the ftp option. The uid and uname specify the user under which FTP files are stored in the app's local storage. Enable FTP access with caution, as many apps do not expect external modifications to their data.

    "localstorage": {
      "ftp": {
        "uid": 33,
        "uname": "www-data"
      }
    }

Sqlite

Specify SQLite database files with the sqlite option.

Active SQLite files cannot be backed up with a simple cp. Consistent, portable backups are taken for SQLite files specified in this option.

    "localstorage": {
      "sqlite": {
        "paths": ["/app/data/db/users.db"]
      }
    }

Database files must exist. Missing files cause backup and restore errors.

MongoDB

This addon provides MongoDB 8.0.17.

Exported environment variables:

CLOUDRON_MONGODB_URL=          # mongodb url
CLOUDRON_MONGODB_USERNAME=     # username
CLOUDRON_MONGODB_PASSWORD=     # password
CLOUDRON_MONGODB_HOST=         # server IP/hostname
CLOUDRON_MONGODB_PORT=         # server port
CLOUDRON_MONGODB_DATABASE=     # database name
CLOUDRON_MONGODB_OPLOG_URL=    # oplog access URL (see below)

Request oplog access by setting the oplog option to true:

"mongodb": { "oplog": true }

To debug, use cloudron exec to run the mongo shell within the app context:

cloudron exec

> mongo -u "${CLOUDRON_MONGODB_USERNAME}" -p "${CLOUDRON_MONGODB_PASSWORD}" ${CLOUDRON_MONGODB_HOST}:${CLOUDRON_MONGODB_PORT}/${CLOUDRON_MONGODB_DATABASE}

MySQL

This addon provides a single database on MySQL 8.0.31. The database is pre-created; the application only needs to create tables.

Exported environment variables:

CLOUDRON_MYSQL_URL=            # the mysql url (only set when using a single database, see below)
CLOUDRON_MYSQL_USERNAME=       # username
CLOUDRON_MYSQL_PASSWORD=       # password
CLOUDRON_MYSQL_HOST=           # server IP/hostname
CLOUDRON_MYSQL_PORT=           # server port
CLOUDRON_MYSQL_DATABASE=       # database name (only set when using a single database, see below)

To debug, use cloudron exec to run the mysql client within the app context:

cloudron exec

> mysql --user=${CLOUDRON_MYSQL_USERNAME} --password=${CLOUDRON_MYSQL_PASSWORD} --host=${CLOUDRON_MYSQL_HOST} ${CLOUDRON_MYSQL_DATABASE}

Set the multipleDatabases option to true if the app requires more than one database. When enabled, the following environment variables are injected and MYSQL_DATABASE is removed:

CLOUDRON_MYSQL_DATABASE_PREFIX=      # prefix to use to create databases

All databases use utf8mb4 encoding by default.

mysql> SELECT @@character_set_database, @@collation_database;
+--------------------------+----------------------+
| @@character_set_database | @@collation_database |
+--------------------------+----------------------+
| utf8mb4                  | utf8mb4_unicode_ci   |
+--------------------------+----------------------+

To see the charset of a table, run SHOW CREATE TABLE <tablename>. Columns can have their own collation order, visible via SHOW TABLE STATUS LIKE <tablename>.

OIDC

This addon provides OpenID Connect based authentication.

Options:

"oidc": {
    "loginRedirectUri": "/auth/openid/callback",
    "logoutRedirectUri": "/home",
    "tokenSignatureAlgorithm": "RS256"
}

loginRedirectUri where the user should be redirected to after successful authorization (only URL path, will be prefixed with app domain). Multiple ones can be provided, separated with comma (eg. "/auth/login, app.immich:/").
logoutRedirectUri where the user should be redirected to after successful logout (only URL path, will be prefixed with app domain)
tokenSignatureAlgorithm can be either "RS256" or "EdDSA"

Exported environment variables:

CLOUDRON_OIDC_PROVIDER_NAME=     # The name of the provider. To be used for "Login with {{providerName}}" button in the login screen.
CLOUDRON_OIDC_DISCOVERY_URL=     # .well-known URL for auto-provisioning
CLOUDRON_OIDC_ISSUER=            # main OpenID provider URI
CLOUDRON_OIDC_AUTH_ENDPOINT=     # auth endpoint - mostly optional
CLOUDRON_OIDC_TOKEN_ENDPOINT=    # token endpoint - mostly optional
CLOUDRON_OIDC_KEYS_ENDPOINT=     # keys endpoint - mostly optional
CLOUDRON_OIDC_PROFILE_ENDPOINT=  # profile endpoint - mostly referred to as /me or /profile
CLOUDRON_OIDC_CLIENT_ID=         # client id
CLOUDRON_OIDC_CLIENT_SECRET=     # client secret

PostgreSQL

By default, this addon provides PostgreSQL 14.9.

Exported environment variables:

CLOUDRON_POSTGRESQL_URL=       # the postgresql url
CLOUDRON_POSTGRESQL_USERNAME=  # username
CLOUDRON_POSTGRESQL_PASSWORD=  # password
CLOUDRON_POSTGRESQL_HOST=      # server name
CLOUDRON_POSTGRESQL_PORT=      # server port
CLOUDRON_POSTGRESQL_DATABASE=  # database name

The PostgreSQL addon supports the following extensions:

address_standardizer;
address_standardizer_data_us
btree_gist
btree_gin
citext
cube
earthdistance
fuzzystrmatch
hstore
ogr_fdw
pgcrypto
pg_stat_statements
pg_trgm
pgrouting
plpgsql
postgis
postgis_tiger_geocoder
postgis_sfcgal
postgis_topology
postgres_fdw
uuid-ossp
unaccent
vector
vectors

To debug, use cloudron exec to run the psql client within the app context:

cloudron exec

> PGPASSWORD=${CLOUDRON_POSTGRESQL_PASSWORD} psql -h ${CLOUDRON_POSTGRESQL_HOST} -p ${CLOUDRON_POSTGRESQL_PORT} -U ${CLOUDRON_POSTGRESQL_USERNAME} -d ${CLOUDRON_POSTGRESQL_DATABASE}

Set the locale option to a valid PostgreSQL locale. When set, LC_LOCALE and LC_CTYPE are configured accordingly at database creation.

Proxyauth

The proxyAuth addon sets up an authentication wall in front of the app.

The authentication wall displays a login screen when users visit the app. Users must log in before accessing the app. The login screen uses session (cookie) based authentication. Users can also log in using HTTP Basic auth with the Authorization header.

Set the path property to restrict the wall to a subset of pages. For example:

"proxyAuth": { "path": "/admin" }

Prefix path with ! to exclude matching paths from authentication. For example:

"proxyAuth": { "path": "!/webhooks" }

The basicAuth property enables HTTP Basic authentication. Enabling it allows users to bypass 2FA. Disabled by default.

Set supportsBearerAuth to indicate that the app supports bearer token authentication via the Authorization header. When enabled, all requests with a Bearer token in the Authorization header are forwarded to the app.

This addon reserves two special routes — /login and /logout — which are unavailable to the app.

Cannot add to existing app

Due to a platform limitation, authentication cannot be added dynamically to an existing app. Reinstall the app to enable it.

Recvmail

The recvmail addon enables incoming email for the application.

Exported environment variables:

CLOUDRON_MAIL_IMAP_SERVER=     # the IMAP server. this can be an IP or DNS name
CLOUDRON_MAIL_IMAP_PORT=       # the IMAP server port
CLOUDRON_MAIL_IMAPS_PORT=      # the IMAP TLS server port
CLOUDRON_MAIL_POP3_PORT=       # the POP3 server port
CLOUDRON_MAIL_POP3S_PORT=      # the POP3 TLS server port
CLOUDRON_MAIL_IMAP_USERNAME=   # the username to use for authentication
CLOUDRON_MAIL_IMAP_PASSWORD=   # the password to use for authentication
CLOUDRON_MAIL_TO=              # the "To" address to use
CLOUDRON_MAIL_TO_DOMAIN=       # the mail for which email will be received

The recvmail addon may be disabled when the server is not receiving email for the domain. Apps must handle the case where the above environment variables are absent.

To debug, use cloudron exec to run the openssl tool within the app context:

cloudron exec

> openssl s_client -connect "${CLOUDRON_MAIL_IMAP_SERVER}:${CLOUDRON_MAIL_IMAP_PORT}" -crlf

The IMAP command ? LOGIN username password can then be used to test the authentication.

Redis

This addon provides Redis 8.4.0. Data is persistent and preserved across updates and restarts.

Exported environment variables:

CLOUDRON_REDIS_URL=            # the redis url
CLOUDRON_REDIS_HOST=           # server name
CLOUDRON_REDIS_PORT=           # server port
CLOUDRON_REDIS_PASSWORD=       # password

Skip password authentication by setting the noPassword option to true. Redis is only reachable within the server's internal Docker network, so this is safe.

"redis": { "noPassword": true }

To debug, use cloudron exec to run the redis-cli client within the app context:

cloudron exec

> redis-cli -h "${CLOUDRON_REDIS_HOST}" -p "${CLOUDRON_REDIS_PORT}" -a "${CLOUDRON_REDIS_PASSWORD}"

Scheduler

The scheduler addon runs tasks at periodic intervals (cron).

Configure the scheduler as follows:

    "scheduler": {
        "update_feeds": {
            "schedule": "*/5 * * * *",
            "command": "/app/code/update_feed.sh"
        }
    }

In this example, update_feeds is an arbitrary task name.

schedule values must fall within the following ranges:

Minutes: 0-59
Hours: 0-23
Day of Month: 1-31
Months: 0-11
Day of Week: 0-6

NOTE: scheduler does not support seconds

schedule supports ranges (like standard cron):

Asterisk. E.g. *
Ranges. E.g. 1-3,5
Steps. E.g. */2

command executes through a shell (sh -c) in the same launch environment as the application. Environment variables and volumes (/tmp and /run) are shared with the main application.

Each task has a 30-minute grace period. If a task exceeds 30 minutes and a new instance is scheduled, the running instance is killed.

Sendmail

The sendmail addon enables outgoing email from the application.

Exported environment variables:

CLOUDRON_MAIL_SMTP_SERVER=       # the mail server (relay) that apps can use. this can be an IP or DNS name
CLOUDRON_MAIL_SMTP_PORT=         # the mail server port. Currently, this port disables TLS and STARTTLS.
CLOUDRON_MAIL_SMTPS_PORT=        # SMTPS server port.
CLOUDRON_MAIL_SMTP_USERNAME=     # the username to use for authentication
CLOUDRON_MAIL_SMTP_PASSWORD=     # the password to use for authentication
CLOUDRON_MAIL_FROM=              # the "From" address to use (i.e username@domain)
CLOUDRON_MAIL_FROM_DISPLAY_NAME= # the email Display name to use for the "From" address
CLOUDRON_MAIL_DOMAIN=            # the domain name to use for email sending (i.e only the domain part of username@domain)

The SMTP server does not require STARTTLS. Apps using STARTTLS must accept self-signed certs.

To debug, use cloudron exec to run the swaks tool within the app context:

cloudron exec

> swaks --server "${CLOUDRON_MAIL_SMTP_SERVER}" -p "${CLOUDRON_MAIL_SMTP_PORT}" --from "${CLOUDRON_MAIL_FROM}" --body "Test mail from cloudron app at $(hostname -f)" --auth-user "${CLOUDRON_MAIL_SMTP_USERNAME}" --auth-password "${CLOUDRON_MAIL_SMTP_PASSWORD}"

> swaks --server "${CLOUDRON_MAIL_SMTP_SERVER}" -p "${CLOUDRON_MAIL_SMTPS_PORT}" --from "${CLOUDRON_MAIL_FROM}" --body "Test mail from cloudron app at $(hostname -f)" --auth-user "${CLOUDRON_MAIL_SMTP_USERNAME}" --auth-password "${CLOUDRON_MAIL_SMTP_PASSWORD}" -tlsc

Set the optional flag to true for apps that let users provide their own email configuration. When enabled, all the above environment variables are absent at runtime.

Set the supportsDisplayName flag to true for apps that allow users to configure the sender display name. When enabled, the CLOUDRON_MAIL_FROM_DISPLAY_NAME environment variable is set.

Set requiresValidCertificate to true for apps that require a valid mail server certificate. When enabled, CLOUDRON_MAIL_SMTP_SERVER is set to the FQDN of the mail server. The app is reconfigured automatically when the mail server's domain name changes.

TLS

The TLS addon provides access to the certificates of an app's primary domain.

Apps implementing protocols like IRC or DNS-Over-TLS may need certificate access.

The certificate and key are available as read-only files at /etc/certs/tls_cert.pem and /etc/certs/tls_key.pem. The app restarts automatically when the certificate is renewed.

TURN

The TURN addon provides access to the STUN/TURN service.

Exported environment variables:

CLOUDRON_TURN_SERVER=           # turn server name
CLOUDRON_TURN_PORT=             # turn server port
CLOUDRON_TURN_TLS_PORT          # turn server TLS port
CLOUDRON_TURN_SECRET            # turn server secret

Overview​

Using addons​

Addons​

Docker​

Email​

LDAP​

Localstorage​

FTP​

Sqlite​

MongoDB​

MySQL​

OIDC​

PostgreSQL​

Proxyauth​

Recvmail​

Redis​

Scheduler​

Sendmail​

TLS​

TURN​

Overview

Using addons

Addons

Docker

Email

LDAP

Localstorage

FTP

Sqlite

MongoDB

MySQL

OIDC

PostgreSQL

Proxyauth

Recvmail

Redis

Scheduler

Sendmail

TLS

TURN