Building custom packages

[girish]

This is a concise guide to building and installing custom packages. For a more detailed explanation, see https://cloudron.io/documentation/packaging/tutorial/.

Prerequisites

1. Make sure you have docker installed. Also, sign up for a docker hub account (https://hub.docker.com/) and use docker login to login to the docker hub account.

2. Install the Cloudron CLI tool: npm install -g cloudron. This requires you to install nodejs for npm to work.

Log into cloudron

$ cloudron login my.example.com
Username: girish
Password: *********
2FA Token (if enabled): 
Login successful.

$ cloudron list
<will list your apps>

Build the app

All our app packages are open source. You can get them here - https://git.cloudron.io/cloudron (repos with the -app suffix).

For this tutorial, we will build the ghost app.

$ git clone https://git.cloudron.io/cloudron/ghost-app
$ cd ghost-app
$ cloudron build
Enter repository (e.g registry/username/org.ghost.cloudronapp2): girish/ghost

The above will build the docker image and push it into docker hub as girish/ghost repository.

Install the app

$ cloudron install
Location: blog

This will install the app you just built into blog.example.com.

Update the app

If you make any changes, you have to rebuild the app and update the cloudron with the latest image.

$ git pull # get latest repo changes
$ cloudron build
$ cloudron update --app blog

The update command will update the blog.example.com app with the image we just built.

That's it!

[alphagroup]

This post is deleted!

[ericsanchez]

Hello Girish thank you for this explainer,

Which CLI are you putting these commands in, your local machine, the Cloudron CLI, or the Linux server's?

Also, if you want to install a custom build at a url location that is not the url from my.example.com but has been verified in the Cloudron dashboard and is able to have other Cloudron apps installed - how does one do that via this CLI method?

My first guess would be

Location:

app.otherdomain.com

Would this be correct?

Also, When you said Docker has to be installed, is that on your Cloudron, your local machine, or your Linux server? One more thing, would custom builds use the CLoudron's MySQL database?

Thank you!

[timconsidine]

@ericsanchez

• the cloudron CLI needs to be installed on your local machine (not the server)

• yes you can put app.otherdomain.com as the location providing otherdomain.com has been added to Domains & Certs

• Docker needs to be installed on your local machine for the app building/packaging process

• custom builds can use cloudron's MySQL if you specify it as an add-on in the CloudronManifest.json for the app you are building. You will need to reference the credentials in the Dockerfile you are building.

[Grienauer]

@girish I have 2 questions:

1. Ist there any chance, that one can add a new folder to the "local storage addon" (persistence layer)?
   Because currently only /app/data is a thing to use here. This is quite narrow/specific, as other applications maybe need other folders.
2. is it possible to have more than one container for an application? some Apps are build to work with multiple, and there is no chance to move that together upstream.

[girish]

@Grienauer

1. We haven't yet had a case where different data directories of apps cannot be symlinked to a subdirectory /app/data . It keeps backup/restore logic simple if we limit to one folder. Do you have an app in mind which cannot do this?

2. Usually, we manage to change apps to use supervisor and thus package multiple containers into one. I guess it's possible to implement this, we haven't yet.

[tronical]

Quick question for my sanity: Suppose I want to apply some changes to an app (say mattermost), build them „locally“ and make our production install use them, are these the correct steps:

• fork the app repo
• make changes
• run cloudron build
• run cloudron update

Is that correct?

[timconsidine]

@tronical personally I do this process :

• fork the repo
• make changes
• docker build etc.
• docker push etc
• cloudron install etc.

Maybe I should learn cloudron build but I am an old dog with limited brain space

My build script (usually in folder above the app dev folder) :

#!/bin/bash

if [ "$#" -lt 1 ]; then
    echo "Usage: $0 <image-name> [cache|nocache] <appname.yourdomain.tld>"
    exit 1
fi

# Get the directory from which the script was called
BUILD_DIR="$(pwd)"

if [ "$2" = "cache" ]; then
    echo "Building with cache ..."
    docker build --platform linux/amd64 -t $1 "$BUILD_DIR"
else
    echo "Building with no cache ..."
    docker build --no-cache --platform linux/amd64 -t $1 "$BUILD_DIR"
fi

docker push $1
cloudron install --image $1 --location $3

e.g. ../cld.sh dockerregistry.yourdomain.tld/appname:version cache appname.yourdomain.tld