This episode got Johannes and me building Cloudron. A way to run apps on our servers without becoming full-time sysadmins. Ten years on, we have been lucky to build a stable company and a great community that actually cares about self-hosting. Thank you for that!

Now, on to Cloudron 10 already!

Mail server

Mail is the piece of self-hosting people give up on first, given the complexity. Stubborn as we are, we keep investing in it to make it simple. If you think email cannot be reliably self-hosted, give us a try! You will have a working mail server in under 20 mins - batteries included. Most of that time will be spent try to get an API token for your DNS 😀

In v10, forwarding lives on the mailbox. We also add ARC (Authenticated Received Chain) headers, so forwarded mail can still prove it was genuine.

Relay tokens let apps and scripts send through the server without a mailbox password.

There is a global allow and deny list for spam, and you can attach notes to mailboxes.

Webmail

The webmail apps we enjoyed like Rainloop, then SnappyMail have unfortunately been abandoned ☹️. We decided it was about time to build our own webmail client.

Mail is a new webmail client specifically made for Cloudron.

Fast search. One-click spam control. Create filters from a message. Integration with Contacts and Calendar. You know, the things you expect from modern web mail. Right now we are playing catch up and simply making it feature complete before starting to work on ideas that a generic IMAP client cannot do. We will write that up in a separate post.

VPN protection

These days you can point an agent at the source repository of an app and find vulnerabilities in a jiffy. Keeping apps updated is good, but sealing internal apps off the internet is better. We built VPN protection to restrict specific apps to WireGuard or OpenVPN.

First, install the VPN app. It is self-service - users generate their own device keys.

Then protect specific apps with that VPN.

When connecting without a VPN:

Container Registry

Cloudron’s app deployment workflow was built primarily for the Cloudron team. With AI, it is easier than ever to create custom packages and share them with other users. So we built Container registry: an OCI-compatible registry with a build server in the same app. Read more about it. And oh, the Community Appstore is nearing 100 apps!

Ubuntu 26.04

We have added support for Ubuntu 26.04 LTS Resolute Raccoon. It is the default for new installations. Existing servers can follow the upgrade guide. Note: Ubuntu 22.04 and 24.04 is still fully supported.

Single Sign-on

Ideally, after logging into the Cloudron dashboard, a user can use mail, Cubby and GitLab immediately, without entering a new password in each app.

LDAP got us part of the way, but it is not proper SSO. The app still sees the raw username and password. From a security standpoint, this was “acceptable” when we packaged everything ourselves, but not so good with all the new third-party packages.

So we have been moving packages to OpenID Connect (OIDC) where only Cloudron sees the password. As of this writing, 93 packages are on OIDC, the 11 proxyAuth apps already moved, about 25 still on LDAP. Getting there! 😄

You can also see which apps a user can access, and why.

Login sessions

The profile now lists Cloudron browser and CLI login sessions.

Other notable changes

• Infomaniak as a DNS provider
• Personal access tokens are now called API tokens
• Admins can create an app password that authenticates as another user
• Password reset accepts a passkey as 2FA
• TOTP backup codes
• Email notification when an app updates successfully
• Certificates and DNS sync show last run time and status
• Backups preserve file modification times
• Redis: maxmemory policy and a persistence flag
• SCIM can list groups and admin roles
• Security: sanitize HTML and markdown in the dashboard, enforce 2FA with the external LDAP connector, app links can no longer point at internal IPs

What’s coming next

Head over to our forum to learn more about what’s coming in our next release - 10.1.

Install Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

wget https://cloudron.io/cloudron-setup
chmod +x ./cloudron-setup
./cloudron-setup

With the rise of AI, it is easier than ever to experiment with custom apps and packages. We have made it a priority to simplify deploying and sharing them.

Source builds

In Cloudron 9.1, we made a fundamental change: packages can be built on the server itself, without the Docker Builder. New versions of the CLI default to this server-side workflow (cloudron install / cloudron update upload the source and build there), while still supporting the dedicated builder.

Community App Store

For sharing, we introduced Community packages. Third-party packagers publish a URL that anyone can use to install the package. As with the App Store, community packages pick up updates when the packager releases them.

To help people find those URLs, we launched the Community App Store. This has been an enormous success. Over 89 packages at the time of writing, all published in the last two months!

Introducing the Container Registry

The remaining gap was hosting. A community package still needs a Docker image that other Cloudrons can pull. The old cloudron build command was written mainly for our own app store workflow - building in a standalone builder, pushing the build into a registry and then submitting the package.

In Cloudron 10, that split goes away. The new Container Registry app both builds and hosts images, just like any modern registry. cloudron build is gone. The new cloudron builder build (similar to the Docker CLI) builds on the Container Registry and stores the image there.

Some features of the new Container Registry:

Docker/OCI compatible registry

It speaks the usual registry protocol. docker login/push/pull as you would with any other registry. It is a general-purpose container registry and can be used outside Cloudron i.e. the Cloudron CLI is only needed for deploying on Cloudron.

Browsable catalog

Repositories and tags are visible in the web UI: digests, sizes, platforms (including multi-arch), pull counts, and last pushed or pulled times. Search in the top bar finds repositories, tags, and builds.

Repository settings

Each repository can be public (anonymous pull) or private (login required for pull and push). Tags can be mutable or immutable.

Builds

cloudron builder login and cloudron builder build send the build context to the registry. It builds with BuildKit and hosts the image in the same app. Builds appear in the UI with live logs and status.

This is also a security improvement over the old Docker Builder. That app built on the host Docker daemon, so a build could affect the rest of the server. Here, BuildKit runs inside the Container Registry app itself. Builds are sandboxed to the app and never touch the host Docker daemon.

Build from triggers or webhooks

Builds can be automatically triggered on a source code push using the GitHub/GitLab integration.

Tag expiry

A common issue with self-hosting a registry is running out of disk. Tag expiry keeps only the newest N tags in each repository and deletes the rest. This is currently a global setting but future versions will support it per repository.

Give it a try!

Cloudron Registry can be installed from the App Store on Cloudron 10. Use the latest Cloudron CLI (v9.0.3) to point cloudron builder at it.

Every server with an open SSH port is subjected to brute force attacks and there are many ways to prevent these.

Fail2Ban, obfuscating the port from 22 to something else, configuring SSHD:

PermitRootLogin no
PasswordAuthentication no

Awesome!

You have done your due diligence to ensure no one can access your server except you.

But remember this Hackathon you attended? You went to grab a drink and left your Notebook unlocked and someone swiftly stole your SSH private keys.

Since that day this person accessed your server and you never noticed.

Get information about successful SSH authentications

You could set up a monitoring solution like Zabbix to get alerts or similar software.

But now you have to maintain another system.

Start simple, let the system itself send you notifications about successful SSH authentifications!

Edit your SSHD config /etc/ssh/sshd_config and ensure the following is configured:

UsePAM yes
ExposeAuthInfo yes

Now create a /usr/local/bin/ssh-notify.sh file:

sudo touch /usr/local/bin/ssh-notify.sh
sudo chmod 755 /usr/local/bin/ssh-notify.sh

Edit the /etc/pam.d/sshd file and append at the end:

session optional pam_exec.so quiet /usr/local/bin/ssh-notify.sh

Test and restart your sshd service:

sudo sshd -t
sudo systemctl restart ssh

Now we can code what ever we want in the /usr/local/bin/ssh-notify.sh file.

For example we could send a mail:

#!/bin/sh
[ "$PAM_TYPE" = "open_session" ] || exit 0

TIME=$(date -Is)
HOST=$(hostname)

MAIL_FROM="ssh-alerts@domain.tld"
MAIL_TO="you@domain.tld"
SMTP_URL="smtps://smtp.your-provider.com:465"
SMTP_USER="ssh-alerts@domain.tld"
SMTP_PASS="your-smtp-password"

MAIL=$(printf 'From: %s\nTo: %s\nSubject: SSH login: %s@%s from %s\nDate: %s\n\nTime:    %s\nUser:    %s\nHost:    %s\nFrom IP: %s\nTTY:     %s\nService: %s\n' \
  "$MAIL_FROM" "$MAIL_TO" "$PAM_USER" "$HOST" "$PAM_RHOST" "$(date -R)" \
  "$TIME" "$PAM_USER" "$HOST" "$PAM_RHOST" "$PAM_TTY" "$PAM_SERVICE")

printf '%s' "$MAIL" | curl -s -m 10 --url "$SMTP_URL" \
  --user "$SMTP_USER:$SMTP_PASS" \
  --mail-from "$MAIL_FROM" \
  --mail-rcpt "$MAIL_TO" \
  --upload-file - >/dev/null 2>&1 &

exit 0

Now you get a mail every time a successful SSH authentification happens and it looks like this:

Time:    2026-08-06T09:04:43+00:00
User:    root
Host:    my-domain-told
From IP: I Am Not Publishing my IP here!
TTY:     ssh
Service: sshd

Send the data elsewhere!

Instead of writing more complex BASH script we can just send the data somewhere else for example N8N.

With a N8N Webhook node we can receive data, so here is the BASH script to send the data to a N8N Webhook:

#!/bin/sh
[ "$PAM_TYPE" = "open_session" ] || exit 0

esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr -d '\n'; }

BODY=$(printf '{"time":"%s","user":"%s","rhost":"%s","tty":"%s","service":"%s","host":"%s"}' \
  "$(date -Is)" "$(esc "$PAM_USER")" "$(esc "$PAM_RHOST")" "$(esc "$PAM_TTY")" \
  "$(esc "$PAM_SERVICE")" "$(esc "$(hostname)")")

curl -sk -m 5 -X POST "https://n8n.domain.tld/webhook/b234e48d-9ad3-4cf3-a2ab-4586d1b6755e" \
  -H "Content-Type: application/json" \
  -H "Authorization: ae46c075fe6a629efb1eaa5c5b1672a7" \
  -d "$BODY" >/dev/null 2>&1 &
exit 0

From there we can do what ever we want the data like store them in a SQLITE database and send a Telegram notification.

For those unaware, Cloudron is a platform that makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

Cloudron 9.2 adds a new SCIM addon, MySQL 8.4 and notification emails improvements.

SCIM addon

System for Cross-domain Identity Management API provides user listing access to apps. With this change, apps are immediately aware of all users without requiring users to log in first.

We have implemented SCIM v2. See the documentation for more information.

MySQL 8.4

MySQL 8.0 has reached end of life, and Cloudron now upgrades installations automatically to MySQL 8.4. We have tested all app packages with MySQL 8.4 to ensure compatibility, so the transition is seamless and requires no manual intervention from users.

HTML notification emails

Notification emails now include HTML variants in addition to the existing plain text format, resulting in a more polished and readable experience across mail clients. Email templates can also be tested directly from the “Send test email” button.

Other Notable Changes

• postgresql: remove old vecto.rs extension
• Move configure/admin page link if any into the info view
• dyndns: randomize the cron job that syncs the dns

What’s coming next

Head over to our forum to learn more about What’s coming in our next release - 10.

Install Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

wget https://cloudron.io/cloudron-setup
chmod +x ./cloudron-setup
./cloudron-setup

For those unaware, Cloudron is a platform that makes it easy to run web apps like n8n, WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

Notifications view

The notifications panel has been redesigned with read/unread state management.

Two new notifications help you stay on top of updates:

• Automatic app update failure - when an app fails to auto-update e.g., due to an add-on incompatibility or resource constraint)
• Manual platform and app update required - when Cloudron platform or an installed app has a pending update that requires manual intervention

Let’s Encrypt ARI support

Certificates are renewed automatically based on suggested renewal times provided via ACME Renewal Information (ARI). Benefits of ARI include reducing load spikes at the CA, faster revocation response, and smarter scheduling. Renewals typically occur 1 month before expiry.

Community apps

Third-party developers can now publish app packages independently using a CloudronVersions.json file. Community apps receive automatic updates when the developer publishes new versions. Around 25 community apps are already available.

Packaging: Backup Hooks & Persistent Dirs

Three new manifest fields (backupCommand, restoreCommand, and persistentDirs) have been added to make it possible to package database apps properly. Directories like /var/lib/postgresql can now persist across container updates, while backup and restore hooks can export and import logical database dumps so that snapshots are always consistent and portable across versions.

Source builds

Apps can now be built directly on the server using cloudron install and cloudron update. The CLI uploads the source directory to the server, which builds the Docker image and starts the app, eliminating the need for a local Docker setup or external build service. For those who prefer building locally or offloading to a dedicated server, alternative build methods are still available.

Backup Integrity Check UI

The “Check integrity” action in the backup menu downloads the backup metadata from remote storage, verifies its signature, and validates all backup files against recorded checksums and sizes.

Filemanager Treeview

The file manager has a tree view in the left panel, making it easy to navigate deeply nested directory structures. Drag and drop across different folders is much simpler since both the source and destination can be visible at the same time.

Passkeys

Passkeys enable passwordless login using a hardware security key, platform authenticator (fingerprint, Face ID), or password manager. A passkey can also serve as a second factor alongside a password.

Click Set up next to Passkey in the profile view to begin the registration process.

The login screen provides a “Log in with a passkey” option that authenticates without requiring a username or password.

Event Log: Contextual Search

Searching the email and system event logs now highlights matching entries in place instead of filtering out non-matching ones. This preserves the surrounding context, making it easier to understand what happened before and after each hit. Next and previous buttons allow quick navigation between matches.

Lazy Service Start

Services like MongoDB, MySQL, PostgreSQL, and TURN are now started lazily, only spinning up when an installed app requires them. This significantly conserves memory and CPU on servers where not all services are in use.

Automatic Update Policy

Updates can now be configured with three policies: Disabled, Apps only, or Platform & Apps. When enabled, a schedule controls which days and hours updates are applied.

Other Notable Changes

• App passwords now support expiry dates
• DigitalOcean Spaces: added missing ATL1, BLR1, and SYD1 regions
• File manager: the terminal button automatically changes to the current directory
• Support for CardDAV/CalDAV well-known endpoints
• CLI: switched to a web-based browser login flow, leveraging existing 2FA and passkey authentication without caching passwords locally
• i18n: added Czech translations. Thank to archos
• Backup logs are now more terse and concise
• App operator: fixed display of backup progress and logs
• Location: the UI now shows which DNS records are being overwritten
• Backup storage: removed the local disk provider

What’s coming next

Head over to our forum to learn more about What’s coming in our next release - 9.2.

Install Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

wget https://cloudron.io/cloudron-setup
chmod +x ./cloudron-setup
./cloudron-setup

If you made it till here, here’s a bonus - starting from Cloudron 9, you don’t need to sign up anymore for a Cloudron.io account 🤗.

For those unaware, Cloudron is a platform that makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

New UI

Cloudron 9 introduces a completely redesigned interface. The new UI is mobile-first by design, working seamlessly across phones, tablets, and desktops.

After a year of development, we've rebuilt the dashboard from the ground up using Vue.js 3.5, replacing 10 years of Angular 1.x code. To power the new interface, we developed Pankow—our open-source component library.

Some screenshots:

Multiple backup sites

Cloudron can now back up to multiple destinations. Each destination, also known as Backup site, can use a different storage provider and schedule. You can also choose what to store on each site - everything, only selected apps or everything except some apps. For example, back up everything to your primary Digital Ocean Spaces bucket daily, while sending some critical apps to a secondary attached disk storage for extra redundancy.

Live graphs

The Server view now displays real-time and historical graphs for CPU, memory, disk I/O, and network I/O with selectable timeframes.

Backup stats & integrity

Cloudron 9 now tracks backup statistics for every backup. You can see the backup size, backup contents (file count & app count), and the time it took to create the backup in the backup info dialog.

A hidden feature is that integrity information is now stored alongside the backups. Each backup includes a SHA256 checksum and file size for verification. This allows detection of corrupted backups before restoration, ensuring only valid backups are used. The verification UI is coming in Cloudron 9.1, which will allow you to manually verify backup integrity at any time.

Multiple docker registries

Multiple private Docker registries can now be configured (previously limited to one), with credentials automatically selected based on the image's registry hostname.

Hetzner Cloud DNS

Hetzner is migrating its DNS Console into Hetzner Cloud. We have added support for the new Hetzner Cloud DNS API. Migrate your domain first and then choose the new provider in the Domains view.

Synology C2

Synology C2 is now a supported backup destination. Create a backup site with C2 credentials to store your backups.

Vanity nameservers

Domains can now use custom (vanity) nameservers like ns1.yourdomain.com instead of provider defaults. Enable the option in advanced settings to bypass nameserver verification checks.

SSHFS optimizations

Hetzner Storage Box is a widely used SSHFS backup destination. Performance optimizations have been made to the SSHFS storage backend to skip FUSE calls and use SSH directly. Users can expect 10-100x speed improvements when using the rsync backup format.

New docs

Documentation has been migrated from MkDocs to Docusaurus. The API is now fully documented with complete endpoint references and examples

Notifications

New email notifications: server reboot required, update failures, and low disk space alerts (triggered at 90% capacity).

We are also working on a new Notifications view for 9.1 .

Other Notable Changes

• Software updates: Haraka (3.1.2), Docker (28.1.1), Redis (8.2.2), MongoDB (7.0.28 - this fixes mongobleed)
• Support for Ubuntu 20.04 is deprecated
• API keys of domains is periodically validated
• Optional addons are disabled by default for new installations
• mail: Brevo mail relay
• App backup runs separately in a background and does not block app operations
• Security: API tokens can now be restricted to specific IP addresses or subnets
• Gravatar support for profile pictures is dropped
• Admins can manage profile pictures of users
• OCSP support has been removed. Let's Encrypt has now uses CRLs.
• OpenID: Workaround bug in Cloudflare Access
• CSP/Robots has common patterns
• mail: add rbl6 check

What's coming next

Head over to our forum to learn more about What's coming in our next release - 9.1.

Install Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

wget https://cloudron.io/cloudron-setup
chmod +x ./cloudron-setup
./cloudron-setup

If you made it till here, here's a bonus - starting from Cloudron 9, you don't need to sign up anymore for a Cloudron.io account 🤗.

For those unaware, Cloudron is a platform that makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

Cloudron 8.3 upgrades the base docker image and provides seamless upgrade of the databases.

New base image

Cloudron apps and addons use an Ubuntu 24.04 LTS based image. The new docker image ID is cloudron/base:5.0.0@sha256:04fd70dbd8ad6149c19de39e35718e024417c3e01dc9c6637eaf4a41ec4e596c. Please update the Dockerfile of your custom apps to use this as the base .

Database upgrades

A core part of Cloudron's self-hosting approach is that users shouldn't have to worry about database choices or database versions that are used by apps. The app packaging mechanism makes the appropriate choices based on the app's preferences.

This release contains many upgrades to the underlying databases and frameworks. The upgrade procedure is entirely transparent and hands-off.

• PostgreSQL is upgraded from v14 to v16
• MySQL is upgraded to v8.0.41
• MongoDB upgraded from v6 to v7
• Redis is upgraded to v7.4
• PHP 8.3 is now the minimum in all apps
• Default node version is 22.14.0 TLS
• Solr, used by mail server for FTS, is upgraded to v9
• Default python is 3.12

Database connection commands

You can now use cloudron_<db> to connect to the database from the Web Terminal. So, you can cloudron exec and then cloudron_mysql to connect to mysql without having to type out those pesky env vars.

What's coming next

Head over to our forum to learn more about What's coming in our next release - 9.

Install or update Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

To update an existing installation, simply click on the 'Update now' button on your dashboard.

For those unaware, Cloudron is a platform that makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

Cloudron 8.2 includes support for Sqlite addon, Mail attachment search, OIDC Provider Name Customization, Device Mounts, App Archive, Parallel Tasks, Email notifications, Quay fallback & many bug fixes.

Sqlite Addon

We are seeing more self-hosted applications support Sqlite. Sqlite databases have to be backed up carefully since a simple cp might copy a corrupt database when it's not in WAL mode.

We have added support for Sqlite addon. Like with other databases, Cloudron now takes portable backups of Sqlite databases listed in CloudronManifest.json.

OIDC Provider Name Customization

The Cloudron Name set in the Branding view is now automatically set as the OIDC Provider Name.

App packages can use the new CLOUDRON_OIDC_PROVIDER_NAME environment variable to customize the text of their login buttons. Here's Immich and Grafana making use of the OIDC Provider Name in their login buttons.

Device Mounts

Apps like OpenHAB, Home Assistant, Emby, Jellyfin have device integrations and require access to devices on the host. A list of host devices to be made available to the app can now be specified in the Devices section.

Parallel Tasks

Cloudron had a global lock (in code) preventing operations like backups, updates and app operations from proceeding in parallel. We have removed this global lock and replaced it with a more granular app level lock. A full backup or a Cloudron update can now run in parallel with app operations.

App Archive

The App Archive feature provides a way to uninstall an app and have the safety mechanism of easily restoring it later. When an app is archived, it is uninstalled from the server, but its latest backup is stored in the App Archive.

The App Archive is located in the Backups view.

Mail Attachment Search

Cloudron Mail will index mail attachments using Apache Tika when Full Text Search is enabled.

Email Notifications

In older Cloudron versions, we used to send email notifications by default to all admins. This was considered too spammy and was removed. We have brought email notifications back with the ability for each user to control what emails they want to receive.

Personal email notification preferences can be configured in the Notifications view:

Quay Fallback

DockerHub seems to use first 64 bits of IPv6 address for rate limiting. Unfortunately, this results in many Cloudrons hitting rate limits incorrectly. As a workaround, we have started pushing our app images to Quay.io under the username cloudron . When a pull from DockerHub fails, the code fallsback to pulling from Quay.io .

Other Notable Changes

• mail: Update Haraka to 3.0.5
• Update docker to 27.3.1
• Security: Samy Mahi reported a critical vulnerability which allows Cloudron admins to get SSH access. We thank Samy for making a responsible disclosure to us (README and REPORT).
• Slow disks can be excluded from periodic disk usage collection.
• postgres: add support for vector extension.
• groups: add events to eventlog
• Hetzner: add Helsinki location for backups
• scheduler: create jobs with Cloudron Time Zone setting
• Gandi: add support for Personal Access Tokens

What's coming next

Head over to our forum to learn more about What's coming in our next release - 9.

Install or update Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

To update an existing installation, simply click on the 'Update now' button on your dashboard.

Waiting for new apps to appear in the Cloudron app catalog is one way to address missing features. Last weekend, I decided to explore what it takes to get a new app up and running.

In this forum post, I shared my thoughts on a missing piece for de-Googled Android phones: a FindMyDevice server. To be fair, I’ve never lost a phone or been robbed, but having everything set up just in case gives me peace of mind.

I had heard of Docker before and experimented with Dockerfiles and docker-compose. I also tried out the beginner apps mentioned in the Cloudron documentation and, in the past, set up a private registry and the Cloudron build service. So, the mise en place was already done before getting started. The rest should be easy.

TL;DR: It took me nearly 8 hours to get the app running, ensure it worked properly, and make sure individual configuration changes persisted through app updates.

Basics - where to start

While it’s possible to create an app package using Docker build on your local computer, it’s not the ideal approach. Instead, you’ll want to use the Cloudron Build Service (CBS). The primary reason for choosing CBS is the bandwidth available in the data center where your Cloudron instance is hosted. Building apps involves downloading and uploading large amounts of data, often several gigabytes. This can be especially challenging in Germany, where slow household internet infrastructure makes such tasks cumbersome.

There’s no real need to use a self-hosted Docker registry, but since we can, we go ahead and install the Cloudron Container Registry (CCR) from the Cloudron app store.

You’ll also need a Cloudron instance where you have admin privileges. This allows you to configure the Cloudron instance to use a private registry, install apps, and connect your Cloudron CLI to the instance.

One of the final steps is to install the Cloudron CLI on your personal computer.

Documentation, configuration, first challenge

Follow these links to read about the installation and configuration. Once everything is set up and working, try out one of the ‘Hello World’ examples.

Cloudron CLI - Documentation
Cloudron Build Service - Documentation
Cloudron Container Registry - Documentation
First challenge - hello world app

The moment the ‘Hello World’ app works, it’s time for fireworks! 🎆

Which app to start with?

If you’ve never looked into the complexity of apps, start with a simple one. By “simple”, I mean ideally a Go binary.

Bird’s-eye view of Cloudron app architecture

The typical Cloudron app runs as a Docker container on the Cloudron platform. The app code, which you want to update without affecting user changes, is stored on a read-only partition (/app/code/). User data and allowed changes are stored on a read-write partition (/app/data/).

There are many open-source projects out there that scatter user data across the file system. Dealing with such tools can be challenging, as it requires a deep understanding of the software. A symbolic link can sometimes offer a solution, but managing more than five of them starts to feel completely unmanageable.

Many open-source projects require databases or in-memory data structure servers like Redis. In their Docker Compose files, they typically bundle these services together. Cloudron’s approach is to offer these services as so-called add-ons, which you can activate in your Cloudron manifest. The benefit for users: after installing 10 apps that require a PostgreSQL database, you won’t end up with 10 separate PostgreSQL installations on your server.

Why Go (in my use case)?

I came across the FindMyDevice server and decided to try it out as a Docker Compose installation. Upon inspecting the architecture, I found the following components:

• A Go binary
• A SQLite database
• A configuration file
• An Nginx example file
• A complete web UI in a folder

So, it felt feasible as my first personal adventure in app packaging.

Where should it be stored? What questions should you ask?

The Go binary is code and requires no user input, so it goes to /app/code/

The app has no other option for storing data than SQLite, meaning we can’t use a database add-on from the Cloudron platform. Since the app stores user data in the SQLite database, it must be placed in /app/data/.

Some settings in the configuration file depend on the user’s decisions, which is why it has to be stored in /app/data/.

Since the Cloudron app platform handles the full reverse proxy and Let’s Encrypt flow, we don’t need the Nginx example file. /dev/null is your friend.

I decided not to dive into the complexities of web UIs, multilingual support, and all the potential feature requests (especially once users realize what’s possible), so I placed the entire folder in /app/code/.

How to start?

I decided to work with a real-world (and live) app package. In my case, I chose the Vault app. Long story short, it helped, but introduced a lot of unnecessary elements that I didn’t fully understand, so I later handed them over to my friend /dev/null.

To have the same in mind, check out the app package for the FindMyDevice Server

The file structure of an app package

The essentials

Cloudron-Manifest.json

The manifest follows a schema, and most of its structure is self-explanatory. For me, working with the id field was completely new. In the end, it’s simple: normally, you include the app’s domain, but in reverse order.
If you want to package an app that won’t be part of the Cloudron app store, not every property in the manifest is required. However, httpPort is mandatory because it’s used by the reverse proxy functionality and for the health check.

Dockerfile

The Dockerfile is straightforward: start with the base image, define and create the working directory, and use wget to download the package from GitLab. Unzip it into the working directory, remove unnecessary files, copy the relevant files into /app/pkg, and set up the start command.

config.yml

Nearly every app requires some configuration. In my case, I found the project’s config.example.yml file.

UnixSocketPath, UnixSocketChmod, PortSecure, and PortInsecure don’t make sense in a Cloudron context. The rest of the configuration should be left for the user to customize with their own values.

During my hours of packaging the app, I realized that the server wasn’t capable of using the httpPort defined in the manifest. Instead, it defaulted to a random port, which wasn’t ideal for the intended goal. In the end, I had to add the PortInsecure variable and set it to match the port specified in the manifest.

Since we can, we often tweak defaults. However, to avoid frustrating users, it’s important to address potential support issues—such as the fact that only 8080 works as the PortInsecure variable in my package.

start.sh
To be fair, the hardest part was feeling like I needed to be a developer to better understand the underlying magic.

set -eu ensures the script crashes when something is undefined instead of running with unspecified behavior. Since we chose localstorage as an add-on in the manifest, we need to create the /app/data folder to store user or app-specific data.

The if-then-fi loop checks whether config.yml exists. If it doesn’t, the file is copied to the specified location.

yq eval -i ".PortInsecure=8080" /app/data/config.yml is part of the magic I hadn’t encountered before. From what I understand, it searches for the PortInsecure value in the config file and updates it to the correct port. Since every change to the config requires an app restart, and start.sh runs on each restart, the user can modify and save a different port—but not in a persistent state. (potential support issue solved.)

chown -R cloudron:cloudron /app/data changes the owner of the files to the correct user.

The exec gosu cloudron:cloudron /app/code/findmydeviceserver serve --db-dir=/app/data --config=/app/data/config.yml --web-dir=/app/code/web starts the server with some configuration options with the correct user.

LICENSE

Every Cloudron app package is released under an open-source license, which is why we include a License file.

more than nice to have

• DESCRIPTION.md
• README.md
• CHANGELOG
• logo.png
• screenshots

They’re nice to have, but they become necessary once the app is submitted to the Cloudron app store.

Sanitation

• .dockerignore
• .gitignore

Normal in software development.

Challenge accepted and completed!

The moment I took this photo: Unbelievable. The initial package works.

App store

There’s a lot of work to be done after the initial packaging to bring the app to the app store, but that’s a story for another day.

Cloudron

https://www.cloudron.io/get.html
https://forum.cloudron.io/category/4/support

For those unaware, Cloudron is a platform that makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

Cloudron 8.1 includes support for Hetzner Object Storage, Gandi PAT and OpenID Groups. It also fixes regressions in Cloudron 8.

Hetzner Object Storage

Hetzner recently released their S3-Compatible Object Storage . In the Cloudron dashboard, you can choose Hetzner Object Storage as the destination for your backups.

Gandi PAT

Gandi has obsoleted the old API Keys and introduced Personal Access Tokens. Users hosting their domains in Gandi.net are encouraged to move to this new scheme at the earliest. Simple choose the token type as Personal Access Token (PAT) in the Domains view.

OpenID Groups

We have added groups claim in OIDC to convey group membership information for a user. In addition, refresh token support has also been enabled.

Other Notable Changes

• node.js was updated to 20.18.0
• dashboard: various mobile and dark mode fixes
• private registry: add cloudron as a provider
• porkbun: API endpoint changed to https://api.porkbun.com
• filemanager: fixed many regressions including broken file upload
• log viewer: handle multi-line messages

What's coming next

Head over to our forum to learn more about What's coming in our next release - 8.2.

Install or update Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

To update an existing installation, simply click on the 'Update now' button on your dashboard.

For those unaware, Cloudron is a platform that makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

Cloudron 8.0 has many new features including support for Ubuntu 24.04 LTS (Noble Numbat), IPv6 only servers, Dashboard List view, Login Page background, deSEC integration, File manager dark mode, Admin Notes, Admin Checklists & lots of bug fixes.

Ubuntu 24.04 LTS

Canonical recently released it's new Ubuntu LTS 24.04 LTS Noble Numbat . Cloudron 8 supports Ubuntu 24.04 and it is also the recommended Ubuntu version for new installations. Note that we will continue to support Ubuntu 20.04 and Ubuntu 22.04 for the foreseeable future.

Users on older Ubuntu versions can upgrade to Ubuntu 24.04 by following our guide.

IPv6 Only Servers

Recently, there has been a change that Cloud Providers like AWS, Hetzner have started to charge for IPv4 addresses. Cloudron 7.1 added IPv6 support but still required an IPv4. Now with Cloudron 8, we support servers which do not have any IPv4.

We have tested IPv6 only server setups on AWS, Hetzner, Upcloud & Vultr and they work great! As a heads up, IPv6 is a totally separate network protocol from IPv4. As such, if you want to host public facing websites and apps, you should still use servers with IPv4.

Dashboard Enhancements

Apps can be viewed as a List in the Cloudron Dashboard .

API Docs

Cloudron API is now stable and fully documented .

Reworked Filter UI

The filter UI has been reworked.

Use / as shortcut to quickly start searching for a specific app.

The filter options are now shown inline and sticky instead of the transient popup in previous releases. You can also filter by tag(s).

Login Page Background

The background image for the login pages can be set in the Branding view.

File Manager Dark Mode

File Manager now has a dark mode!

deSEC Integration

deSEC is a free DNS hosting service, designed with security in mind. Running on open-source software and supported by SSE, deSEC is free for everyone to use.

To use the deSEC integration, move your domain over to deSEC and then choose deSEC provider in the dropdown in the Domains view.

App Notes

App specific notes can be saved in markdown format. Notes are shared by admins. All Admins and App Operators can view and edit them.

Admin Checklist

Cloudron's manifest has been extended to have a checklist property. The checklist is a list of items to be completed post installation. The items can be individually tracked - completed or not, by whom and when. Examples include changing the default admin credentials, reviewing registration settings, etc.

Checklist appears in the Info section of the app.

When a Checklist item is marked as done, the username and date of completion is tracked for audit purposes.

OpenID everywhere

We have adjusted the app packages of over 60 apps to use Cloudron OpenID Connect. Because the authentication flow goes via the Cloudron Auth Endpoint, we can enforce 2FA, enforce rate limits and various security measures which were impossible with the previous LDAP integration.

Apps that use the proxyAuth addon will also now use OIDC automatically.

Troubleshooting tool

Dashboard down? Instead of reaching out to support as the first step, we have implemented all our troubleshooting techniques in the cloudron-support tool. Simply run cloudron-support --troubleshoot on the server, and you will get a good idea of what has gone wrong. See the troubleshooting docs for more information.

App Resources

We have reworked the memory and CPU allocation mechanism for apps.

The memory limit that you set in the Resources view translates the Max RAM the app can use. Apps get unlimited swap.

The previous CPU shares functionality is now CPU limit. With this, you can restrict how much max CPU an app can use.

System Resolver

Prior to Cloudron 8, we use unbound as the system wide DNS resolver. Unfortunately, bugs in unbound and various network restrictions has generated much networking related issues.

To remedy this, we have drastically cut down the role of unbound . Cloudron 8 uses whatever was the server's default system resolver at installation time (usually systemd-resolved). unbound is still used for various recursive DNS queries like propagation and RBL checks.

Non-AVX Servers

We removed support for servers without AVX support in Cloudron 7.5. Turns out low-power systems like the ZimaBoard, but also Netcup servers and various other providers still have servers without AVX.

With Cloudron 8, support for servers without AVX is back! Unfortunately, MongoDB 5 and above still requires AVX. To handle this, when Cloudron is installed on servers without AVX, MongoDB is disabled. As a result, you won't be able to install various apps like Rocket.Chat, Meemo, NodeBB & Wekan.

Hetzner Storage Box

Many users use Hetzner Storage Box for storing very large backups. We looked into optimizing backup speed for this specific case.

For SSHFS mounted Storage Box, we have implemented server side copying. Server side copying allows us to implement hard links correctly and remote copying is 1000x faster. For this reason, we recommend configuring your Storage Box to use SSHFS.

Other Notable Changes

• Backups: a long standing issue that backups used to get stuck at zero Mbps is now fixed.
• Dashboard: font and color improvements
• notfound page: better message when navigating by IP address
• CIFS: enable seal encryption by default
• NFS: disable rpcbind service. we only support nfsv4 mounting
• OVH Storage: Fix location URLs and add RBX region
• AMI: IMDv2 support
• Mailer: add html version of test mail
• Backups: fix issue with s3 backend where files missing in remote was not detected correctly
• Backup cleaner: do not remove the backup in progress

What's coming next

Head over to our forum to learn more about What's coming in our next release - 8.1.

Install or update Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

To update an existing installation, simply click on the 'Update now' button on your dashboard.

For those unaware, Cloudron is a platform that makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

Cloudron 7.7 has many new features including Port Range support, Docker improvements, OIDC Avatar Support, MongoDB 6, User Language Persistence, Cancelable uploads & lots of bug fixes.

Port Range

Cloudron already provides a way for apps to expose TCP and UDP ports. From 7.7, an app can expose a port range using the optional portCount field in the manifest. This feature is required for various apps like AzuraCast and MiroTalk.

We have published MiroTalk SFU, a Fast Real-Time Video Conference platform that uses an SFU, that uses this feature.

Docker Improvements

The docker daemon starts a userland proxy service for port forwarding whenever a port is exposed. This proxy consumes a lot of CPU resources since it is created per exposed port. In 7.7, we have disabled the userland proxy in docker.

Apps can now also specify an array of log files instead of stdout/stderr using the logPaths field in the manifest.

Container logging now uses Unix Domain Sockets instead of UDP. This frees up UDP ports for apps.

OIDC Avatar Support

For apps that support it, Cloudron OIDC now exposes user avatars via the picture claim.

MongoDB 6

MongoDB has been upgraded to 6.0. Apps can now use several new features of MongoDB including improved support for Time Series Data, more operators and enriched queries.

Cancelable Uploads

File uploads can be canceled midway in the File manager.

User Language

• Users can select their Language preference in the profile view. This setting is now persisted across browsers and devices. Note that the login screen still follows the global language setting chosen by the admin.

Other Notable Changes

• backupcleaner: fix bug where preserved backups were removed incorrectly
• oidc/ldap: fix display name parsing to send anything after first name as the last name
• email: use secp256r1 curve certificates to improve deliverability
• dashboard: use native slider element for app memory and CPU
• dashboard: preserve app link paths
• backups: deleted apps must also be displayed in contents
• Postgres: add vecto.rs extension support for immich

What's coming next

Head over to our forum to learn more about What's coming in our next release - 8.0.

Install or update Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

To update an existing installation, simply click on the 'Update now' button on your dashboard.

For those unaware, Cloudron is a platform that makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

Cloudron 7.6 has many new features including MongoDB 5, New base image, OVH DNS backend, DNSimple DNS backend, System Info, Editable Volumes, Color-keyed notifications, External Directory Connector improvements & lots of bug fixes.

Important Deprecation Notice

Cloudron 7.6 upgraded MongoDB to 5.0 which requires AVX. For this reason, Cloudron 7.6 will not install on CPUs without AVX. See https://forum.cloudron.io/topic/8785/avx-support-in-your-vps-server for more information.

New Base Image 4.2.0

The docker base image is now based on Ubuntu Jammy 22.04 LTS. The digest is:

cloudron/base:4.2.0@sha256:46da2fffb36353ef714f97ae8e962bd2c212ca091108d768ba473078319a47f4.

OVH DNS

OVHCloud is the largest hosting provider in Europe. If your domain is hosted on OVH, choose OVH in the drop-down when configuring a domain.

DNSimple

DNSimple is a secure & simple DNS hosting provider . If your domain is hosted on DNSimple, you can choose DNSimple in the provider drop-down in the Domains view.

System Info

SMBIOS information like Vendor and Product is displayed in the System view.

Color-keyed Notifications

Notifications are colored based on their type. Important notifications requiring action including reboot required, certificate renewal failures, backup failures are marked in red. Updates are highlighted with blue.

Editable Volumes

Mount configuration of Volumes like host name, username, password and remote location can be changed at any time.

External Directory

The External Directory connector allows users from an existing LDAP or Active Directory to authenticate with Cloudron. Logs and sync progress can be viewed using the Logs dropdown on the top right.

We have also made many improvements in this release:

• 2FA Behavior: When using another Cloudron as an authentication provider, 2FA of the external directory is used. When using other providers, users can setup 2FA locally.
• User Attributes: The user's role and active state are local and not synced from LDAP.
• Groups Behavior: When Sync Groups is enabled, groups will be automatically created and users will be associated. External Groups are readonly and cannot be edited.
• Sync Behavior: The local directory is synced with the external directory every 4 hours.
• Keep/Make Local: This feature has been removed. It never worked properly because local users were overwritten with the next sync.

Other Notable Changes

• turn: add DDoS mitigation settings
• mail: add option to enable/disable Virtual All mailbox
• app proxy: Host header is set to match the proxy domain instead of the target domain
• oidc: add oidc logo as login indicator for apps
• dyndns: update DNS every 10 mins
• Cleanup backup validation mount point
• dashboard: remove nginx config of old domain when domain changed
• roles: admin role can access branding and networking
• dockerproxy: allow child containers to access volumes
• postgres: enable cube, vector and earthdistance extensions
• support: replace ticket section with help section
• firewall: increase blocklist size to 262144
• profile: changing email now requires password

What's coming next

Head over to our forum to learn more about What's coming in our next release - 8.0.

Install or update Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

To update an existing installation, simply click on the 'Update now' button on your dashboard.

For those unaware, Cloudron is a platform that makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server and keep them up-to-date and secure.

Cloudron 7.5 has many new features including Contabo Object Storage, Trusted IPs, New File Manager UI, Task Logs, Optional App Services, Virtual All Mails Mailbox & lots of bug fixes.

Important Deprecation Notices

Support for Ubuntu 18.04 ended with Cloudron 7.4. This release does not support Ubuntu 18.04 and attempts to update will fail.

This is the last release of Cloudron to support CPUs without AVX support. AVX support is required for MongoDB 5.0. See https://forum.cloudron.io/topic/8785/avx-support-in-your-vps-server for more information.

Contabo Object Storage

Contabo Object Storage is S3 compatible Object Storage from Contabo. To configure Cloudron to use Contabo Object Storage, choose the Contabo Object Storage in the Backups Configure UI.

Trusted IPs

When Cloudron is behind an HTTP(S) proxy like Cloudflare or Nginx Proxy Manager, you can set the IP address(es) of the proxy as trusted. Doing so will make sure Cloudron trusts the values of various proxy related HTTP headers like X-Forwarded-For in the request.

New File Manager UI

The new File Manager UI supports very large folders and lazy loading. Internally, we are slowly porting our frontend to Vue.js and PrimeVue . The File Manager, Web Terminal & Log Viewer are already ported. The code is structured as a shared component library named Pankow. This allows us to reuse the file listing in various apps like Surfer and Cubby.

Task Logs

Cloudron has many background tasks - Certificate renewal, Dynamic DNS, Sync DNS, Mail Server Location Change, Backup Cleaner etc. The history and logs of all the background tasks is now exposed in the UI.

Optional App Services

Redis and TURN configuration of an app can be turned on/off dynamically in the Services section.

Virtual All Mails Mailbox

Cloudron mail server is now configured to expose a virtual All Mails folder (thanks to Dovecot). Some mail clients (like SnappyMail) do not support recursive folder search. Using this folder, you can easily search all your emails in such clients. You can read more about the status of search in various email clients in our blog.

Other Notable Changes

• Update Redis to 7.0.11, Docker to 23.0.6 and Haraka to 3.0.2
• Ionos Profitbricks: add new regions Berlin and Logrono
• mail: fix issue where client IP was leaked in headers
• Dashboard now uses OIDC for login
• Redirections: Use 301 (permanent) instead of 302 (temporary) for redirections. This is better for SEO.
• Major overhaul of the REST API. Please note that the docs are still being updated as of this writing to reflect the new API routes.
• Fix import via SSHFS and CIFS.

What's coming next

Head over to our forum to learn more about What's coming in our next release - 7.6.

Install or update Cloudron

New to Cloudron? Get started for free by running with 3 simple commands on your server.

To update an existing installation, simply click on the 'Update now' button on your dashboard.

• How does the mail client perform search?
• What's the best way to search in the mail client?
• Will the mail client benefit from having a "All Mails" folder?
• Should all users be automatically subscribed to "All Mails" folder?
• What is the current status of search in the mail client (bug reports, issues etc)?

Search Index

On the server side, we use Dovecot as our IMAP server. IMAP has a "SEARCH" command. Per the RFC 3501, the SEARCH command is a case-insensitive substring operation. By default, Dovecot does a slow sequential search through all messages.

To speed up search, Dovecot can index messages using the Solr FTS Engine. Solr has a "schema" which specifies the kind of index it maintains. A schema can specify the min/max length of works, min/max ngram length for start/end string matching, stop words, stemming algorithm, word delimiters etc. A number of compromises need to made to keep the size of the index reasonable. On Cloudron, we went with:

• Minimum 3 letters needed for a search
• Can only search for start of a string (EdgeNGramFilter)
• Uses Porter Stem

IMAP Search

While we maintain a search index on the server, we are still reliant on the email client to actually issue the SEARCH command. The SEARCH command only searches a single folder and is not recursive. The mail client has to recurse each folder, issue SEARCH command and collate the results.

The MULTISEARCH command in RFC 7377 allows searching multiple folders in a single shot, but there is no support for this in Dovecot yet. This mail thread suggests creating a virtual folder which has all the mails to search in.

Adding the virtual folder in Dovecot is easy enough, but do mail clients support searching nicely with it? Let's see.

Roundcube

Roundcube is able to search recursively using IMAP SEARCH. For this, one has to select "Entire message" and scope "All folders" before searching.

Roundcube shows only subscribed folders. If the "All Mails" folder was auto-subscribed the search results appear twice (despite the "All Mails" folder having the \ALL flag).

Unfortunately, there is no way keep the search options selected to 'Entire Message' and 'All folders' by default. We have submitted a patch upstream to remedy this.

SOGo

SOGo is able to search recursively using IMAP SEARCH . For this, you have to click on the three dots to the right of the INBOX, select BODY in criteria and search.

A caveat: SOGo shows all folders by default. This means that All Mails folder will appear even if not subscribed automatically. If you search using the three dots to the right of the mailbox name, search results appear twice.

A nice touch in SOGo UI is that it shows the folder name WIP in the search results.

SnappyMail

SnappyMail does not implement recursive SEARCH . However, it's the only client I am aware of that implements MULTISEARCH. Unfortunately, there is no way to test this because Dovecot doesn't implement it.

The suggested solution for SnappyMail is to search by selecting the virtual All Mails folder. Caveat: the free flowing search input box does not search the email body! You can click the options arrow to the right on the search input box and put the text to search in the body field in the resulting popup. Quite cumbersome but functional. We have made a suggestion to search the body by default here .

K-9

In K-9 , searches are local by default. After you search once, One clicks the "cloud icon" in top of the search results bar to get server side results. Unfortunately, the devil is the details and the functionality barely works:

• The server search does not search the message body.
• The server search does not recurse.
• On the plus side, lots of search functionality is planned.

Thunderbird

Thunderbird has a multitude of ways to search:

• Global Search (Ctrl+K)
• Quick Filter bar (Ctrl+Shift+K)
• Classic Search (Ctrl+Shift+F)

The first two searches only search locally (GLODA or Global Database in thunderbird lingo).

The Classic Search has options to search remotely and recursively. The search results also show the folder in which the mail was found. The Open in Folder button will also open the corresponding folder and mail in the main window.

There is a long open bug report on make the QuickSearch automatically use Server side search. It was opened 13 years ago, so I won't hold my breath for that one :-)

Conclusion

Of the analyzed mail clients, only SnappyMail can benefit from the All Mails virtual folder. Rest of them can already do recursive search or in the case of K-9 cannot search even if we had the virtual folder.

We have decided to add the All Mails folder considering that maybe there are other mail clients that can benefit from it. At least, it's not harming the ones we analyzed.