In my previous post, I gave an introduction to Cloudron's REST API. We also have a CLI tool that allows you to install, configure and test apps on your Cloudron.
The original intent of the CLI tool was simply to help package and test apps. But it's scope has since been expanded to do various app and server maintenance tasks. In this post, we will see how to use the CLI tool to manage apps on your Cloudron.
Installing Cloudron CLI
On Linux and Mac OS X, you can install the CLI tool on your laptop using the following command:
sudo npm install -g cloudron
As of this writing, the CLI tool only works with the Linux Bash Shell on Windows 10 (Cygwin and MSYS is known to not work).
You can add the following command to end of your
.zshrc for tab completion:
. <(cloudron completion)
Login to Cloudron
The first step is to login to your Cloudron. We will use the demo cloudron to test our commands.
$ cloudron login demo.cloudron.me Enter credentials for demo.cloudron.me: Username: cloudron Password: cloudron Login successful.
There is an analogous
cloudron logout, in case you want to switch to using another Cloudron.
$ cloudron list Id Location Manifest Id State ------------------------- --------- ---------------------------------------- ------- 020816d3-...-a4b4649c2df9 jira firstname.lastname@example.org running 0d502574-...-c0554f72174e whatsapp email@example.com running 267a79ad-...-b4f2a81eb566 instagram firstname.lastname@example.org running 7c8073e9-...-99d9a08b80c6 slack email@example.com running c1ccac6f-...-4af951397112 github firstname.lastname@example.org running dd5c7893-...-4b7f195f4e19 blogger email@example.com running
You can then pass the
Id or the
Location as the
--app parameter to identify the app to the commands below.
If you want program readable output, use
cloudron inspect instead.
You can install apps from the Cloudron App Store like so:
$ cloudron install --appstore-id com.nextcloud.cloudronapp Location: files App is being installed with id: 0bcbd4f6-b7fd-4938-bde1-d236513ce9a1 => Waiting to start installation => Cleaning up old install => Registering subdomain => Downloading image ....... App is installed.
cloudron open --app files to open the app in your browser. You can use
cloudron uninstall --app files to uninstall the app.
Configure the app
To change the location of an existing app or to adjust the port bindings (for example, to change the git SSH port), use the
cloudron configure command.
To move the app above to a new location
$ cloudron configure --app files --location myfiles Will configure app at location files App is being configured with id: ec13f1f6-9c6c-4d60-a93f-90ca7e9c8d68 => Cleaning up old install . => Registering subdomain => Downloading image App is configured.
Cloudron maintains backups of each app individually. By doing so, you can backup, restore and clone apps individually instead of a server level (i.e compared to VPS "snapshots").
Create a backup
To create a backup at this instant (note that backups are created automatically every night):
$ cloudron backup create --app myfiles => Backing up . => Wait for health check App is backed up
To list the backups of an app:
$ cloudron backup list --app myfiles Id Creation Time Version ---------------------------------------------------------- ------------------- ------- appbackups/app_ec13f1f6-9c...8d68_2017-03-06_v0.3.3.tar.gz 2017-03-06T02:47:40 0.3.3
Restoring from a backup
To restore from any of your backups:
$ cloudron restore --app myfiles
Restoring from a backup also rolls back the application code. This is required because old backup data is most likely incompatible with new app code.
Cloning from a backup
To install an app that is a clone of an existing app, use the
clone command and pass the backup id in the
The following command clones an existing app:
$ cloudron clone --app myfiles --backup latest Location: dolly App cloned as id a426fdec-94e7-42c5-a1f4-ab1a5ac22427 => Waiting to start installation => Registering subdomain => Downloading image => Download backup and restore addons ....... => Creating container . => Setting up collectd profile => Waiting for DNS propagation .... => Wait for health check........ App is cloned
To download the backup and decrypt automatically:
$ cloudron backup download --decrypt appbackups/app_ec13f1f6-9c6c-4d60-a93f-90ca7e9c8d68_2017-03-06-024727-352_v0.3.3.tar.gz
If you download the encrypted backups, you can decrypt it using
openssl aes-256-cbc -d -pass "pass:$pass" where
$pass is the backup encryption key. You can then unpack the backup using
tar zxvf <backup.tar.gz>.
Manipulating App files
On the Cloudron, each app is it's own silo (also known as a "container"). Every app gets it's own file system and changes made by one app are invisible to others. This design allows one to manipulate apps independently without affecting others.
The Cloudron also marks most of the directories in the app's file system as
read only. By making app containers immutable, Cloudron can easily update apps from one version to another because it knows exactly what is changing when the app is running.
If an app wants to persist any files across updates, it has to store them in
/app/data. All other changes to the filesystem (like
/run) will be lost across updates and restarts.
You can get a "shell" into the app's file system using the
exec command. As explained above, any changes you make to the filesystem only affect the app in question.
For example, to install an TinyTinyRSS theme into
$ cloudron exec --app ttrss root@app:/app/code# cd /app/data/themes root@app:/app/data/themes# wget https://raw.githubusercontent.com/levito/tt-rss-feedly-theme/master/feedly.css --2017-03-06 19:38:34-- Resolving raw.githubusercontent.com ... 126.96.36.199 Connecting to raw.githubusercontent.com:443... connected. HTTP request sent, awaiting response... 200 OK Length: 38282 (37K) [text/plain] Saving to: 'feedly.css' feedly.css 100%[=====================================>] 37.38K --.-KB/s in 0.001s 2017-03-06 19:38:35 (32.1 MB/s) - 'feedly.css' saved [38282/38282] root@2384d1fe1ecc:/app/data/themes# ls compact.css default.php feedly.css night.css
You can push files or directories to an app's
/app/data as follows:
For example, to push a local theme file
reeder.css from your laptop to the
$ cloudron push --app ttrss reeder.css /app/data/themes/ Uploading [==============================================================] 100%: 0.0s
You can pull files as well:
$ cloudron pull --app ttrss /app/data/themes/reeder.css .
To get the status of an app:
$ cloudron status --app files Id: 0bcbd4f6-b7fd-4938-bde1-d236513ce9a1 Location: files Version: 0.3.3 Manifest Id: com.nextcloud.cloudronapp Install state: installed Run state: running
To get the logs of an app:
$ cloudron logs --app reader ... <snipped> ... 12:16:25 [main] 172.18.0.1 - - [06/Mar/2017:20:16:25 +0000] "GET / HTTP/1.1" 200 2368 "-" "node-superagent/1.8.5" 12:16:35 [main] 172.18.0.1 - - [06/Mar/2017:20:16:35 +0000] "GET / HTTP/1.1" 200 2368 "-" "node-superagent/1.8.5" 12:16:46 [main] 172.18.0.1 - - [06/Mar/2017:20:16:45 +0000] "GET / HTTP/1.1" 200 2368 "-" "node-superagent/1.8.5" ... <snipped> ...
To restart the app:
$ cloudron restart --app files => Waiting for app to be stopped => Waiting for app to be started . => Wait for health check App restarted
In addition, you can use
cloudron stop to "pause" an app if you want to free up resources temporarily and use
cloudron start to start it up later. Unlike uninstalled apps, stopped apps are part of the Cloudron backup.
The Cloudron CLI tool can be used to do various app related tasks on the Cloudron. To explore the CLI tool further, run