Skip to content

Apps

Installation

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

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:


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.

Configuration

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

Location

The Location field (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 302. 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 302).

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.

Labels and Tags

Label is the text that is displayed for the app on the dashboard below the icon. 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.

The label and tag of an app can be changed in the Display section of the app's configure UI:

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 memory 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 email notification to Cloudron admins.

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

Memory limit includes swap

The memory limit specified above is a combination of RAM and swap space and is calculated by the swap ratio of the server. For example if the server has 4G RAM and 4G swap, the ratio is 50%

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 Shares

By default, all apps use as much CPU as they need. When CPU cycles are constrained, the CPU share setting determines how the linux kernel should share CPU usage across apps. The CPU share setting is a percentage relative to each app. It priorotizes CPU resources for the available CPU cycles. It does not reserve specific CPU access.

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

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.

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:

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.

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.

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.

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).

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.

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: /

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 * * * *.

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 server 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.

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.

The split view can be used to move around files easily across directories:

FTP 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>/.

Staging environment

When doing website development, it is useful to have production and staging environments. Cloudron's backup and clone features can be used to create a workflow as follows:

  • Install the app in staging.example.com. Do edits and development as desired.
  • Once ready, make a 'snapshot' of the app by making an app backup
  • Use the clone UI to install the app into prod.example.com.

The same mechanism above can be used bring latest production data to staging.

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.

Uninstall

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

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

Backups are not removed

App backups are not removed when it is uninstalled and are only cleaned up based on the backup policy. Apps can always be re-instated from their backups using the CLI tool.

Filter

Apps in the dashboard can be filtered using one or more of the following filters:

  • Group name
  • App State
  • Domain name