Skip to main content

Tutorial

Overview​

This tutorial walks through packaging a web app for Cloudron.

A Cloudron app is a Docker container that runs within the platform's managed environment. The key differences from a standard Docker setup:

  • The filesystem is readonly at runtime. Only /tmp, /run, and /app/data are writable. This prevents code from being overwritten and ensures reliable updates.
  • Databases, caching, and email are provided as addons through environment variables — apps do not manage their own services. Shared resources enable reliable, platform-managed backups.
  • A CloudronManifest.json file declares the app's metadata, port bindings, and addon requirements.

By the end of this tutorial, a working app will be running on Cloudron with a build-install-update development loop.

The steps involved:

  • Create a Dockerfile for the app.
  • Create a CloudronManifest.json declaring addons and metadata.
  • Install the app using cloudron install. The source is uploaded and built on the server.
  • Update the app using cloudron update.

Prerequisites​

CLI​

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

sudo npm install -g cloudron

Login to the server:

cloudron login my.example.com
Opening browser for authentication...
Login successful.

Run cloudron --help for a list of all available commands. See CLI docs for a full reference.

Sample app​

Several sample repositories are available to get started. Use cloudron init to create a bare bone app, or clone one of the following:

git clone https://git.cloudron.io/docs/tutorial-nodejs-app
git clone https://git.cloudron.io/docs/tutorial-typescript-app
git clone https://git.cloudron.io/docs/tutorial-php-app
git clone https://git.cloudron.io/docs/tutorial-supervisor-app

All published packages are open source and available at git.cloudron.io/packages. Any of these can serve as a starting point.

Install​

From the app directory, run cloudron install. The CLI uploads the source directory to the server, which builds the Docker image and starts the app:

# switch to the package dir
cd tutorial-nodejs-app

# install the package
cloudron install
No build detected. This package will be built on the server.
Location: tutorial
App is being installed.

 => Queued .
 => Registering subdomains
 => Registering location tutorial.example.com .......
 => Building image
 => Waiting for propagation of tutorial.example.com ..
 => Wait for health check

App is installed.

The .dockerignore file controls which files are included in the upload. Keep this file up to date to avoid uploading unnecessary files.

Open the app in a browser:

# open the app in the browser
cloudron open

Logs​

View the app's log output using cloudron logs. Use cloudron logs -f to follow logs in real time:

cloudron logs
Using cloudron app.example.com
16:44:11 [main] Server running at port 8000

Update​

After making changes, run cloudron update from the app directory. The source is uploaded and rebuilt on the server:

# updates app after creating a backup. use --no-backup to skip backup.
$ cloudron update
No docker image detected. Creating source archive from this folder.

 => Waiting for app to be updated
 => Queued .
 => Backup - Uploading app snapshot testapp.example.com
 => Backup - Copying snapshot/app_1d7fca7c-d01c-435f-a228-5a49d34e35e9 to 2026-02-28-145956-737/app_testapp.example.com_v0.1.0 with concurrency of 10
 => Deleting old containers .......
 => Building image
 => Wait for health check ......

App is updated.

Use cloudron install and cloudron update repeatedly during development.

Debugging​

Inspecting the filesystem​

Use cloudron exec to open a shell inside a running app:

cloudron exec

Repair mode​

When an app keeps crashing, cloudron exec may not stay connected. Use cloudron debug for these situations. In debug mode, the app pauses without running the Dockerfile's CMD and the filesystem becomes read-write:

cloudron debug

Disable debug mode with cloudron debug --disable.

Alternative build methods​

The default cloudron install and cloudron update commands build the app directly on the server. This is the simplest workflow but can be resource-intensive on the server, especially for large apps. Two alternative methods are available.

Local Docker build​

This method builds an image using Docker installed on the local machine. The built image is pushed to a Docker registry and installed on Cloudron with cloudron install --image. Other users can also install the image on their own Cloudrons, or receive updates through a CloudronVersions.json file.

Run docker login to authenticate with the registry. cloudron build builds the image locally, pushes it to the registry with a timestamp-based tag, and remembers the repository name for subsequent runs:

# login to the registry
docker login

# build the package
cloudron build
Enter docker repository (e.g registry/username/com.example.app): username/myapp

Building Dockerfile locally as username/myapp:20260228-014051-30452a2c5
...
Pushing username/myapp:20260228-014051-30452a2c5
...
20260228-220941-186ea03bc: digest: sha256:b949112b5a598d491cb7f5df53a8c06def0a0512e0c75099f92b12e6c2225d96 size: 4286
...

Then install:

# install the built app
cloudron install
Location: tutorial
App is being installed.

 => Queued .
 => Registering subdomains
 => Registering location tutorial.example.com .......
 => Downloading image
 => Waiting for propagation of tutorial.example.com ...
 => Wait for health check

App is installed.

Repeat the cycle to update the app:

cloudron build
cloudron update
Private registry

For private registries, configure the registry credentials first. Then prefix the registry to --image, e.g. cloudron install --image docker.io/username/myapp:1.0.0.

Manual build

For full control over tagging and the build process, use docker build and docker push directly, then pass the image with cloudron install --image username/myapp:1.0.0.

Changing repository

To change the saved repository name or start fresh, run cloudron build reset.

Build service​

The Docker Builder App offloads image builds to a separate server in the cloud. This avoids slow image pushes from home or office networks and provides more CPU and RAM for resource-intensive builds.

Install the Docker Builder App on a non-production server, then authenticate:

cloudron build login
Build Service URL: builder.example.com
Build Service login (https://builder.example.):
Token: <token>
Login successful.

After login, cloudron build sends the source to the build service instead of building locally:

cloudron build

Next steps​

The Cheat sheet covers platform-specific considerations for writing the Dockerfile and start script.