Tutorial

Overview​

This tutorial outlines how to package a web app for Cloudron.

Steps to create an app:

• Create a Dockerfile for your app.

• Create a CloudronManifest.json. This file specifies the addons (like database) required to run your app. Environment variables for connecting to the addon are set when the app runs.

• Build the app using docker build and push the image to any public or private docker registry using docker push. To help with the build & push workflow, you can use cloudron build.

• Install the app using cloudron install --image <image>.

• Update the app using cloudron update --image <newimage>.

Prerequisites​

CLI​

The CLI is a command line tool for building and installing custom apps. Install the CLI tool on your PC/Mac:

$ sudo npm install -g cloudron

Login to your server:

$ cloudron login my.example.com
Enter credentials for my.example.com:
Username: girish
Password:
Login successful.

cloudron --help provides a list of all available commands. See CLI docs for a quick overview.

Docker​

Docker builds app images. Install it from here.

Sample app​

This tutorial packages a simple app to demonstrate the packaging flow. Clone any of the following repositories to get started. You can also use cloudron init to create a bare bone app:

• Nodejs App

    $ git clone https://git.cloudron.io/docs/tutorial-nodejs-app

• Typescript App

    $ git clone https://git.cloudron.io/docs/tutorial-typescript-app

• PHP App

    $ git clone https://git.cloudron.io/docs/tutorial-php-app

• Multi-process App

    $ git clone https://git.cloudron.io/docs/tutorial-supervisor-app

All our published apps are Open Source and available in our git. You can use any of those as a starting point.

Build​

The next step is to build the docker image and push the image to a repository.

# Enter app directory
$ cd nodejs-app

# Build the app
$ docker build -t username/nodejs-app:1.0.0 .

# Push the image. if the push fails, you have to 'docker login' with your username
$ docker push username/nodejs-app:1.0.0

Install​

The app image is pulled from the public docker registry without authentication. For private registries, configure the private registry credentials in the Settings view.

Install the app:

# Be sure to be in the app directory
$ cd tutorial-nodejs-app

$ cloudron install --image username/nodejs-app:1.0.0
Location: app.example.com
App is being installed.

 => Starting ...
 => Registering subdomains
 => Downloading image ....
 => Setting up collectd profile

App is installed.

Open the app in your default browser:

$ cloudron open

You should see Hello World on your browser.

Logs​

View the logs using cloudron logs. Follow the logs using cloudron logs -f when the app is running.

See the console.log output in server.js with this command:

$ cloudron logs
Using cloudron craft.selfhost.io
16:44:11 [main] Server running at port 8000

Update​

To update the app, build a new Docker image and apply the update:

$ docker build -t username/nodejs-app:2.0.0 .
$ docker push username/nodejs-app:2.0.0
$ cloudron update --image username/nodejs-app:2.0.0

Use a different tag from the existing installation. With the same tag, the Docker client does not check the registry to see if the local and remote images differ.

Tag docker images using a timestamp to workaround this:

$ NOW=$(date +%s)
$ docker build -t username/nodejs-app:$NOW
$ docker push username/nodejs-app:$NOW
$ cloudron install --image username/nodejs-app:$NOW

The cloudron build command automates the above workflow. The build command remembers the registry and repository name (in ~/.cloudron.json).

You can do this instead:

# This command will ask the repository name on first run
$ cloudron build
Enter repository (e.g registry/username/com.example.cloudronapp): girish/nodejs-app

Building com.example.cloudronapp locally as girish/nodejs-app:20191113-014051-30452a2c5
...
Pushing girish/nodejs-app:20191113-014051-30452a2c5
...

# The tool remembers the last Docker image built and installs that
$ cloudron update
Location: app.cloudron.ml
App is being installed.

 => Starting ...
 => Registering subdomains
 => Creating container

App is updated.

Use cloudron build and cloudron update repeatedly for app development.

Next steps​

This concludes the tutorial on building a custom app.

The development guide covers various platform-specific considerations when writing the Dockerfile.