Using the Cloudron CLI tool (Part 1)
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.