Using the Cloudron CLI tool (Part 1)

By Girish on Friday, March 3rd 2017



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 .bashrc or .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.

Listing apps

$ cloudron list

Id                         Location   Manifest Id                               State  
-------------------------  ---------  ----------------------------------------  -------
020816d3-...-a4b4649c2df9  jira       io.taiga.cloudronapp@0.5.0                running
0d502574-...-c0554f72174e  whatsapp   chat.rocket.cloudronapp@0.17.0            running
267a79ad-...-b4f2a81eb566  instagram  com.electerious.lychee.cloudronapp@0.1.1  running
7c8073e9-...-99d9a08b80c6  slack      org.mattermost.cloudronapp@0.7.2          running
c1ccac6f-...-4af951397112  github     io.gogs.cloudronapp@0.14.1                running
dd5c7893-...-4b7f195f4e19  blogger    org.wordpress.cloudronapp@0.7.2           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.

Installing apps

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.

Use 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 myfiles:

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

Managing backups

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

Listing backups

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 --backup parameter.

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

Downloading backup

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 /tmp, /run) will be lost across updates and restarts.

Shell

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 /app/data/themes:

$ 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 ... 151.101.40.133
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

Pushing files

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 TinyTinyRSS app:

$ cloudron push --app ttrss reeder.css /app/data/themes/
Uploading [==============================================================] 100%: 0.0s

Pulling files

You can pull files as well:

$ cloudron pull --app ttrss /app/data/themes/reeder.css .

Debugging apps

Check status

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

Getting logs

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

Restart app

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.

Summary

The Cloudron CLI tool can be used to do various app related tasks on the Cloudron. To explore the CLI tool further, run cloudron help.