Skip to main content

App packages

Overview​

Cloudron app packages are containerized applications with a separate filesystem from the host server. Understanding how packages work helps you customize and manage your apps effectively.

Package architecture​

Read-only filesystem​

App packages run in a read-only filesystem and cannot be modified. This ensures consistency and security across updates and restarts.

Only these directories are writable:

  • /app/data - Persistent app data (survives restarts and updates)
  • /run - Runtime files (temporary, cleared on restart)
  • /tmp - Temporary files (cleared on restart)

Database access​

Apps have access to databases through addons. Databases are provisioned automatically and accessed via environment variables like CLOUDRON_POSTGRESQL_HOST, CLOUDRON_MYSQL_USERNAME, etc.

Making changes​

File Manager​

Use the File Manager to edit files in /app/data directly from your web browser.

Web Terminal​

The Web Terminal provides access to the full filesystem and includes buttons at the top to quickly access app databases.

Customization approach​

Customization differs per app. Individual package documentation provides specific guidance on what can be changed and how.

For example, the SFTPGo app has a /app/data/sftpgo.json file where users can add custom configuration.

Important restrictions​

Certain settings are managed automatically and should not be changed:

Database configuration​

Database settings (host, port, username, password) are always managed and overwritten on every app restart. These settings should never be changed manually.

Example from SFTPGo start.sh:

# PostgreSQL settings - automatically configured on every restart
yq -i -o json '.data_provider.driver="postgresql"' $config_file
yq -i -o json '.data_provider.name=strenv(CLOUDRON_POSTGRESQL_DATABASE)' $config_file
yq -i -o json '.data_provider.host=strenv(CLOUDRON_POSTGRESQL_HOST)' $config_file

Domains and ports​

Domain names and port numbers are dynamic and patched automatically based on the app's deployment location. These should not be changed.

Email configuration​

Email settings are managed automatically. By default, apps are configured to use the built-in mail server. Some packages have an option to disable email autoconfiguration if you need to configure email delivery manually.

SSO authentication​

User authentication settings related to SSO configuration (hostname, port, username, password) are managed automatically and should not be changed.

Troubleshooting​

If a configuration file resets on its own after editing, the setting is likely managed automatically. Check the app's startup script in the package repository to confirm which settings are overwritten on restart.