Apps¶

Installation¶

Three types of app icons can be added in the dashboard:

App Store Apps
App Links
App Proxy

Icons can be added from the Appstore view:

App Store¶

Apps can be installed from the App Store menu item. Clicking on an app will display information about the app.

Clicking the Install button will show an install dialog:

App Links¶

An App Link is a shortcut to an external web site. Clicking on a App Link simply opens up the website in a new tab on the user's browser.

App Proxy¶

App Proxy is a service that lets one publish a public HTTPS URL endpoint for a non-Cloudron hosted application. When a user visits the public endpoint, App Proxy proxies requests to the hosted application.

When using HTTP proxying, you must ensure that the network between Cloudron and the internal application is secure.

Benefits of using the App Proxy include DNS management, Certificate management, Configurable domain aliases and redirections, setting a custom CSP, setting custom robots.txt and up/down notifications.

You can also specify which users & groups can see the proxy app icon using the Dashboard Visibility setting.

The Upstream URI can have one for the following formats:

http://ip:port or http://[ipv6]:port
https://ip:port or https://ipv6]:port
http://domain:port
https://domain:port

When using https, certificates are not verified.

Updates & Backups

As the app is hosted externally, managing app updates and backups of proxied apps are outside the scope of Cloudron.

Cannot mirror public sites

App Proxy has not been designed to mirror or proxy other people's public sites or domains. The App Proxy sets the Host header to the App Proxy's location when proxying and not the upstream/target domain. You will most likely see a 502 error if you try to mirror public sites.

Protect the upstream

It's a good idea to have a firewall rule in the upstream server to only accept requests from Cloudron server IP.

Configuration¶

Clicking on the gear button will open the app's configure view.

Location¶

Primary Domain¶

The Location field, also known as Primary Domain, is the subdomain into which the app will be installed. Use the drop down selector on the right to choose the domain into which the app will by installed. If the subdomain field is empty, the app will be installed in the bare/naked domain.

Cloudron packages are "relocatable" by design. Changing the location field in the Location section of the app's configure UI will move the app to another domain or subdomain:

Location field can be multi-level

The Location field can be any level deep. For example, you can specify location as blog.dev to make the app available at blog.dev.smartserver.space.

No data loss

Moving an app to a new location is a non-destructive action. Existing app data will be migrated to the new domain.

Secondary Domains¶

Some apps require more than one domain. For example, minio uses two separate domains - one for the UI and one it's API. Other examples include Loomio (websockets domain), CryptPad (sandbox domain) and Traccar (OsmAnd protocol).

Secondary domains can be specified at installation time. Like the Primary domain, they can be changed later in the Location section:

Aliases¶

Some apps can be reached via more than one domain. For example, WordPress multi-site can serve up websites based on the domain name. EspoCRM supports creating customers portals on custom domains.

Aliases can be setup from the Location section in the app's configure UI:

The alias feature is only enabled for select apps since it requires apps to support multiple domains.

Redirections¶

Redirections forward one or more domains to the primary domain with a HTTP 301. They can be setup from the Location section in the app's configure UI:

In the above example, anyone visiting chat2.cloudron.ml or chat3.smartserver.io will be automatically redirected to the main domain chat.cloudron.ml (with a HTTP 301).

The redirection feature preserves any URI components like subpaths in the original request.

www redirection

In DNS, the domains example.com and www.example.com are independent and can point to completely different websites. In practice, it is a good idea to forward one to the other. Do this, by adding www or the bare domain as a redirection.

Port Bindings¶

TCP and UDP port bindings can be configured in the Location section in the app's configure UI:

In the above example, the UDP Port of the VPN app is exposed at port 7194. The TCP Port is disabled.

When enabling ports, remember to also whitelist ports in any Cloud Firewall.

Cloudflare proxying

If you proxy the domain via Cloudflare, port bindings will not work because Cloudflare only proxies HTTP and HTTPS.

Display¶

Label¶

Label is the text that is displayed for the app on the dashboard below the icon.

Tags¶

Tags are a mechanism to tag apps with labels. For example, you can mark specific apps with the customer name and filter apps by customer name.

Icon¶

A custom icon for the app can be set in the Icon section. When not set, the App package's icon is used.

Access Control¶

Access Restriction¶

Many apps in Cloudron are integrated with Cloudron's user management. For such apps, one or more groups or users can be assigned to an app to restrict login. For apps not integrated with Cloudron user management, see the section on controlling the visibility of app icon in dashboard.

Note that Cloudron only handles authentication. Assigning roles to users is done within the application itself. For example, changing a user to become a commenter or author inside WordPress has to be done within WordPress.

Allow all users from this Cloudron - Any user in the Cloudron can access the app.
Only allow the following users and groups - Only the users and groups can access the app.

Dashboard Visibility¶

The Dashboard of a Cloudron user displays the apps that the user can access. For apps that use Cloudron Single Sign-on, the dashboard only displays an app if the user has access to it.

For apps configured to not use the Cloudron Single Sign-on (for example, some public app like a Forum or Chat), the apps are displayed (by default) on the dashboard of all users. Admins can control if an app appears in a user's dashboard using the Dashboard Visibility section in the app's configure UI.

Operators¶

An admin can set user(s) & group(s) as the operators of an app. An app operator can perform configuration and maintanence tasks. Unlike an app admin, an operator cannot uninstall the app or change it's location. Operators cannot clone apps either because they do not have the permissions to install new apps.

An operator will see the gear icon on their dashboard:

On clicking the gear icon, they will see the operator UI:

Info¶

Various app information can be found in the Info section of the app:

App Title and Version - This is the app's title and the upstream app version
App ID - Unique ID of the app instance
Package Version - Version of the Cloudron package. This is distinct from the (upstream) App Version
Installed At - When the app was installed
Last Updated - When the app was last updated

Admin Notes¶

App specific notes can be saved in markdown format. Notes are shared by admins. All Admins and App Operators can view and edit them.

Checklist¶

Checklists provide a mechanism to inform administrators of urgent and security related tasks that need to be carried out at the earliest. Examples include changing the default admin credentials, reviewing registration settings, etc.

Checklist appears in the Info section of the app.

When a Checklist item is marked as done, the username and date of completion is tracked for audit purposes.

Resources¶

Memory limit¶

All apps are run with a memory limit to ensure that no app can bring down the whole Cloudron. The default memory limit of an app is set by the app author at packaging time. This limit is usually the minimum amount of RAM required for the app. Cloudron admins are expected to tweak the memory limit of an app based on their usage.

When an app runs out of memory, Cloudron automatically restarts it and sends an OOM notification to Cloudron admins.

The memory limit can be set by adjusting the slider in the Resources section of the app's configure view.

Unlimited Swap

The memory limit specified above is just the RAM. All apps get unlimited swap.

Low Resource Warning¶

When you try to install a new app, a 'Low Resource Warning' message may be displayed based on the calculation of maximum memory limits of existing installed apps. This is a warning that the server will run out of memory, in case all apps are close to their set memory limit.

The warning is shown based on a conservative estimate, because more often than not, apps use well below their maximum memory limit.

CPU Limit¶

By default, all apps use as much CPU as they need. To constrain the maximum CPU usage, you can set a CPU Limit. If your server has 16 cores, then a setting of 50%, will limit the app to use a maximum of 8 cores at a time.

The CPU limit can be set by adjusting the slider in the Resources section of the app's configure view.

Devices¶

A list of host devices to be mounted into the app can be specified in the Devices section.

Storage¶

Data Directory¶

Apps store their data and assets in the /home/yellowtent/appsdata/<appid> directory. If the server is running out of disk space (in the root filesystem), you can move the app's storage directory to another location. In most cases, this is an external disk mounted on the server. For example, you can mount a DigitalOcean Block Storage or AWS Block Store and move the app's data to that disk.

For example, to move an app's data to an external disk location like /mnt/seagate:

Add the external disk as a volume named seagate.
Go to the app's Storage section and select the volume. An optional prefix may be specifed to store the data in a subdirectory.

Volume Type

cifs and sshfs volumes are unsuitable as an app's data directory as they do not support file permissions and ownership. mountpoint and nfs volumes may or may not work depending on the destination filesystem.

App Data Directory is backed up

The external app data directory is part of the app's backup.

Mounts¶

Apps on Cloudron are containerized and do not have access to the server's file system. To provide an app access to a path on the server, one can create a Volume and then mount the volume into the app. Apps can access any mounted volumes via /media/{volume name} directory in their file system.

For example, to give an app access to an external disk /mnt/music:

Create a volume in the Volumes view name music.
Add an app mount.

The app can access the music files from /media/music (which corresponds to the host path /mnt/songs).

When the read only flag is checked, the /media/music directory is not writable.

Mounts are not backed up

Volumes are not backed up. Restoring an app will not restore the volume's content. Please make sure to have a suitable backup plan if you write to them.

Email¶

Mail FROM address¶

For apps that can send email, Cloudron automatically assigns an address of the form <location>.app. To change this name, go to the Email section in the app's configure UI.

Display name

Support for email address display name depends on the app. If the display name input box is missing, it means that the app doesn't support it (possibly because it uses a dynamic display name). If the display name is empty, the app package provides a suitable default (usually the app's title).

Disable Email Configuration¶

For select apps, you can also disable email auto-configuration using Do not configure app's mail delivery settings. When selected, Cloudron will not configure email delivery settings inside the app, you can set it up yourself.

This is not a mailbox, just an address

The app is simply configured to send mails with the above name. If you want to receive email with the address, be sure to create a mailbox. If a mailbox with the name does not exist, any replies to the email will bounce.

Inbox¶

For apps that can receive email, the inbox address for the app can be assigned in the Email section of the app's configure UI.

When an inbox address is assigned, Cloudron will configure the app to receive mails using that address. It will also generate a dynamic username and password for the app to use to access the inbox.

An inbox address can only be assigned, if the email server for the domain in hosted on Cloudron. If the email server is external to Cloudron, use the "Do not configure inbox" option and configure the app on your own.

Mailbox must be manually created

The app is simply configured to receive mails with the above address. You must create a mailbox for emails to be received by the mail server.

Security¶

robots.txt¶

The Robots.txt file is a file served from the root of a website to indicate which parts must be indexed by a search engine. The file follows the Robots Exclusion Standard. Google has an excellent document about the semantics.

The robots.txt contents of an app can be set in the Security section of the app's configure UI.

By default, Cloudron does not setup a robots.txt for apps. When unset, the app is free to provide it's own robots.txt.

In addition, the Cloudron admin page has a hardcoded robots.txt that disables indexing:

User-agent: *
Disallow: /

Custom CSP¶

The CSP HTTP header instructs the browser to only load scripts, media, images and other resources only from specific sites. Some apps set these headers to be overly restrictive and provide no way to customize them. For such apps, you can override the CSP headers set by the app.

For example, to embed Mattermost in another site, you can set the following CSP policy for Mattermost:

frame-ancestors site.example.com;

HSTS Preload¶

HSTS Preload is a list of sites that are hardcoded into Chrome as being HTTPS only. Most major browsers (Chrome, Firefox, Opera, Safari, IE 11 and Edge) also have HSTS preload lists based on the Chrome list.

Requirements and implications:

Due to the size of the preload list, automated preload list submissions of whole registered domains (bare domain) are accepted.
This will prevent all subdomains and nested subdomains being accessed without a valid HTTPS certificate.
New entries are hardcoded into the Chrome source code and can take several months before they reach the stable version.

When enabled, Cloudron will serve the following HSTS headers:

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

To enable HSTS Preload, enable it in the Security section of the app:

Submission

Cloudron does not automatically submit the domain to the HSTS Preload list. You must do that manually here.

Cron¶

Cron jobs required for the app to function are already integrated into the app package and no further configuration is required. If you want to run additional custom cron commands, you can add them in the Cron section.

Cron commands are run with the exact same context as the app (in a one-off container). This means that they have access to all the same environment and databases as the app itself. They also follow the life cycle states of the app. When an app is stopped, they don't run anymore. The log output of the cron commands can be viewed using the log viewer.

Cron times are specified in UTC.

The schedule pattern can also be one of the following cron extensions:

@service : Run once on app restart or if app is already running.
@reboot : Run once on app restart or if app is already running.
@yearly : Run once a year, ie. 0 0 1 1 *.
@annually : Run once a year, ie. 0 0 1 1 *.
@monthly : Run once a month, ie. 0 0 1 * *.
@weekly : Run once a week, ie. 0 0 * * 0.
@daily : Run once a day, ie. 0 0 * * *.
@hourly : Run once an hour, ie. 0 * * * *.

Chaining commands

The command can be chained using && or '||' . For example, echo "=> Doing job" && /app/data/do_job.sh

Services¶

Redis¶

By default, apps requiring Redis for caching are set up to use a standalone internal redis database. If you want to conserve resources or your usage of the app doesn't necessitate caching, you can disable redis in the Services section.

TURN¶

By default, apps requiring STUN/TURN configuration are set up to use the built-in TURN service. If you prefer to use an external one, this can be disabled in the Services section.

Web Terminal¶

Cloudron provides a web terminal that gives access to the app's file system. The web terminal can be used to introspect and modify the app's files, access the app's database etc. Note that Cloudron runs apps as containers with a read-only file system. Only /run (dynamic data), /app/data (backup data) and /tmp (temporary files) are writable.

The web terminal can be accessed using the Web Terminal button:

Clicking the icon will pop up a new window. The terminal is essentially a shell into the app's file system.

File Manager¶

Cloudron provides a File Manager that be used to modify the app's file system from the browser.

The File Manager can be accessed using the File Manager button:

Clicking the icon will pop up a new window. Note that there are action like Rename, Delete, Change Ownership in the context menu.

SFTP Access¶

Certain apps like WordPress, LAMP, Surfer support access to their data via SFTP. Files can be viewed and uploaded using any SFTP client. The FTP connection information can be displayed by clicking the SFTP Access menu item.

A SFTP client like FileZilla can be used to connect as follows:

Host - sftp://my.cloudron.space (host is the same for SFTP access to all apps)
Username - girish@lamp.cloudron.space (username is different for SFTP access to each app)
Password - Cloudron password (password is the same for SFTP access to all apps)
Port - 222

Only Cloudron admins have SFTP access. To give a specific user access to SFTP of a single app, make them an operator.

Port 222

SFTP service runs at port 222. The server firewall already has this port open. However, you will have to whitelist this port in the Cloud firewall (e.g EC2 Security Group or DigitalOcean Firewall). If the domain is fronted by Cloudflare, use the IP address of the server to connect via SFTP instead of my.domain.com.

Log Viewer¶

To view the logs of an app, click the logs button:

This will open up a popup dialog that display the logs:

Up to 10MB of current logs and one rotated log is retained per app. Logs older than 14 days are removed. The raw logs are located at /home/yellowtent/platformdata/logs/<appid>/.

Graphs¶

The Graphs view shows an overview of the CPU, disk, network and memory usage of the app.

Stop App¶

An app can be stopped using the Stop button from the app toolbar.

Restart App¶

An app can be stopped using the Restart button in the Repair section.

Recovery Mode¶

When an app is not working as expected or keeps crashing, it useful to have the app container in an introspectable state. The File manager is always available but the Web Terminal won't work because the app is continuously crashing. This method can also be used to disable any problematic extensions or plugins preventing the app from starting up.

For such situations, first check the app logs and then place the app in Recovery Mode for debugging. Apps in Recovery Mode:

Start in a 'paused' state. The Web Terminal can be used to start the app manually. By convention, the startup script is located in /app/pkg/start.sh. Run this command to see where the app crashes.
Use the database buttons on the top of Web Terminal to access the app databases.
Cloudron runs containers in a readonly filesystem. In Recovery Mode, the entire filesystem is writable and you can make make changes to the application code. Note that all code changes will be lost when you leave the Recovery Mode!

Archive¶

An app can be archived by using the Archive button in the Uninstall view.

Archiving an app is similar to uninstalling an app. All data associated with the app is removed from the server and the app won't appear in the main dashboard. There are however, key differences:

The latest app backup is kept forever and is not affected by the Cleanup policy. In contrast, when an app is uninstalled, the latest backup is removed based on the Cleanup policy.
The app is moved to the App Archive in the Backups view. Apps in the App Archive can be easily restored. In contrast, when an app is uninstalled, you have to use the App Import mechanism which is more complicated.

Deleting an entry from the App Archive will delete the associated backup based on the Cleanup policy.

Uninstall¶

An app can be uninstalled using the Uninstall button in the app's configure UI.

Uninstalling an app immediately removes all data associated with the app from the server.

App backups are not removed immediately when an app is uninstalled. They are cleaned up based on the Cleanup policy. Provided you still have the backups, an app can be restored using App Import.

Archiving is recommended

If there is the remotest chance that the app might come in handy later, consider Archiving the app instead. This approach will not only free up space on your server but also make it possible to easily restore the app later when you need it.

Version¶

There are two independent versions associated with an app. These are shown in the info section.

The Package version. Cloudron uses semver for it's app packages.
The App version or Upstream version. App version format varies wildly. It can be date based, semver, git commit based, numbers etc.

Install Specific Version¶

When you install an app from the App Store view, it installs the latest package. It is possible to install older packages and older versions of the app, as long as the Cloudron version supports it.

To determine the version, you have to look into the package's source code. All Cloudron app packages are open source and available at https://git.cloudron.io/cloudron . Each app package is in it's own repository and has the -app suffix.

For example, Managed WordPress, GitLab, Espo CRM and so on.

To install a specific package version:

First, determine the desired package version. In each git repo, there is a CHANGELOG . Let's say we want to install WordPress 6.4.3 . For this, we locate this line. The line above says that Package Version 3.6.1 has WordPress 6.4.3.
Go to App Store view and click on the app.
Change the URL bar to ?version=3.6.1 parameter as above to the desired package version and press enter.
Install the app

Automatic update

If you want to stick to the installed version, be sure to disable automatic app updates .

Troubleshooting¶

As a first step, check the app logs to look for errors.

For transient errors like database connectivity error, a simple restart will sort out the issue.
Check if the services used by the app are running in the Services view. If one or more are not running, see the Services docs.
Use the recovery mode for debugging.
If the issue is related to a mis-configuration or an error in some plugin, theme or extension, the approach to fix depends on the app and the tooling the app provides. For example, WordPress plugins can be disabled using WP CLI and Nextcloud can be disabled using occ. Please look into the Cloudron's app docs for hints (Look under Apps in the side bar).
To test if the app starts, run the start.sh script using the Web Terminal. This script is usually located under /app/pkg or /app/code (this is a Cloudron packaging convention).
Once fixed, disable recovery mode. This will start the app.