Skip to content

Apps

Installation

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:


The Location field 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 (i.e at smartserver.space in the picture above).

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.

Configuration

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

Change domain

Changing the location field in the Location section of the app's configure UI will move the app to another domain or subdomain:

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.

Redirections

Redirections 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 (using HTTP 302).

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

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 to be allocated for the app. Cloudron allocates 50% of this value as RAM and 50% as swap.

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.

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.

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.

First, create a volume in the Volumes view:

Then, the volume can be mounted into one or more apps.

Volumes are mounted under the /media directory of the app. In the example above, the app can access 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.

Mail FROM address

For apps that can send and/or receive 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.

Mailbox is not automatically created

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 or assign it as an alias for an existing mailbox. If a mailbox with the name does not exist, any replies to the email will bounce.

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;

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.

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 is displayed in the information Access Control section of the app's configure UI.

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

  • Host - sftp://my.cloudron.ml
  • Username - girish@blog2.cloudron.ml
  • Password - Cloudron password
  • Port - 222

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.

Non admin access

By default, only Cloudron admins have SFTP access. Before giving SFTP access to non-admins especially for apps like WordPress, one should be aware that since the code is modifiable, a non-admin can potentially write code to log the passwords of an admin user and thus compromising the system. If this is not a problem, you can provide SFTP access to non-admin from the Services view -> SFTP -> Configure.

Log viewer

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

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

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 disk and memory usage on your Cloudron.

The Disk Usage graph shows you how much disk space you have left. Note that the Cloudron will send the Cloudron admins an email notification when the disk is ~90% full.

The Apps Memory graph shows the memory consumed by each installed app. You can click on each segment on the graph to see the memory consumption over time in the chart below it.

The System Memory graph shows the overall memory consumption on the entire Cloudron. If you see the Free memory < 50MB frequently, you should consider upgrading to a Cloudron with more memory.

Well Known URIs

Well Known URIs for a domain or subdomain hosted on Cloudron can be setup as follows:

  • Let's say we want to provide a response for https://app.example.com/.well-known/service/client. SSH into Cloudron and create the following file:
mkdir -p /home/yellowtent/boxdata/well-known/app.example.com/service
echo 'response' > /home/yellowtent/boxdata/well-known/app.example.com/service/client
  • The document will be served up immediately.

app.example.com must be hosted on Cloudron

app.example.com must be an app or a redirect to an existing app on Cloudron. Otherwise, the reverse proxy will not handle the domain and return a 404.

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.