Unreachable dashboard

Follow these instructions when the Cloudron dashboard is unreachable. For other issues:

• App issue
• Mail Server issue
• Service issue

Troubleshooting tool

SSH into the server and run the troubleshooting tool: cloudron-support --troubleshoot.

The output identifies broken components. Each test is explained below.

Bash

cloudron-support --troubleshoot

Output

Vendor: Hetzner Product: vServer
Linux: 6.8.0-50-generic
Ubuntu: noble 24.04
Processor: AMD EPYC Processor
BIOS NotSpecified  CPU @ 2.0GHz x 3
RAM: 3911360KB
Disk: /dev/sda1        57G
[OK]	node version is correct
[OK]	IPv6 is enabled and public IPv6 address is working
[OK]	docker is running
[OK]	docker version is correct
[OK]	MySQL is running
[OK]	nginx is running
[OK]	dashboard cert is valid
[OK]	dashboard is reachable via loopback
[OK]	box v8.2.0 is running
[OK]	netplan is good
[OK]	DNS is resolving via systemd-resolved
[OK]	Dashboard is reachable via domain name
[OK]	Domain smartserver.io is valid and has not expired
[OK]	unbound is running

Diagnostics

Node version

Cloudron requires a specific Node.js version. Installing Node.js on the server changes this version. Cloudron does not support base system changes. Follow the output instructions to revert the node version.

IPv6

Some VPS providers enable IPv6 and assign an address but IPv6 routing does not work. Your server cannot reach other IPv6 servers. The tool provides instructions to disable IPv6 as a temporary measure. Contact your VPS provider's support for a long-term fix.

Docker

If docker stops, check journalctl -u docker and systemctl status docker for clues. Docker sometimes obsoletes options between versions. Check for a custom config at /etc/systemd/system/docker.service.d.

Incorrect Docker version

Cloudron requires a specific Docker version. Installing docker or compose on the server changes this version. Cloudron does not support base system changes. Follow the output instructions to revert the docker version.

MySQL

Two instances of MySQL

Cloudron runs two MySQL instances. One runs on the host and is used by the platform. The other is the MySQL addon, runs in a container named mysql, and is shared by apps. This test relates to the host MySQL.

Check the systemd MySQL service using systemctl status mysql. Check for errors and warnings in /var/log/mysql/error.log.

MySQL corruption recovery requires multiple steps. Try the quick restore method below. Otherwise, restore your server from the latest Cloudron backup.

1. Locate the latest box backup in your backup storage: a file named box.tar.gz (tgz) or box (rsync). Extract or locate the file box.mysqldump inside it. Copy this file to some location in your server.
2. Stop box code:

Bash

    systemctl stop box

3. Stop MySQL:

Bash

   systemctl stop mysql

4. Recreate the existing MySQL installation:

Bash

    mv /var/lib/mysql /var/lib/mysql.old
    mkdir /var/lib/mysql
    chown -R mysql:mysql /var/lib/mysql
    mysqld --initialize   # This will dump the MySQL root password in /var/log/mysql/error.log

5. Start MySQL:

Bash

    systemctl start mysql

6. Connect to the MySQL service:

Bash

    # there is no space between p and the password. e.g -pMySecurePassword
    mysql -uroot -p<password from /var/log/mysql/error.log>

7. Change the root password to password:

SQL

    ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

8. Import the database:

Bash

    mysql -uroot -ppassword < /path/to/box.mysqldump

9. Restart the platform code:

Bash

    systemctl restart box

Nginx

nginx serves as the reverse proxy for the Cloudron dashboard and apps. Use journalctl -u nginx and check /var/log/nginx/error.log to investigate why it is not running.

A config may be incorrect or corrupt. nginx configs are at /home/yellowtent/platformdata/nginx/. Delete some files here and make systemctl restart nginx work. You can safely delete nginx certificates and config files. Cloudron regenerates certificates and configs from its database. Once you access the dashboard, go to App -> Repair to regenerate the nginx config.

Dashboard certificate

Invalid DNS API tokens (wildcard certs) or incoming port 80 blocked by the firewall (manual or wildcard DNS) cause invalid certificates.

To fix: visit the dashboard and accept the self-signed certificate in the browser. Go to Domains view and update the DNS API Token. Renew the certs using Domains -> Renew Certs.

API Token may be tied to IP

Some DNS API tokens (Cloudflare, Namecheap) can be restricted by IP. If your server's IP changed, fix the token rules.

Loopback / hairpin NAT

Cloudron configures DNS with the public IP address. Routers without Hairpin NAT support prevent you from reaching the dashboard and apps from inside your network.

Solutions depend on your use case:

• If you use Cloudron and apps only from inside your network, change the network settings to use the local IP address. Cloudron will use the local IP in the DNS instead of the public IP address.

• If you use Cloudron from outside your network as well, purchase a new router that supports hairpin NAT.

• If purchasing a new router is not an option:

  • Configure your network's DNS server to return the Local VM IP for all subdomains in use. When your PC/Laptop accesses a domain, it uses the Local VM IP instead of the public IP to connect to Cloudron. Devices outside the network continue to use the public IP address.

  • Some apps use the domain name to connect with each other (for example, collabora app connects to nextcloud app with domain name). For such cases, configure Cloudron's DNS server unbound to use your network's DNS.

Netplan

Ubuntu uses netplan by default to configure networking. Netplan is optional; your VPS provider could have disabled it. When enabled, configs are at /etc/netplan/50-cloud-init.yaml. This file defines how your server learns about its IP and nameservers. netplan generates systemd (default) or NetworkManager configs (desktop Ubuntu) based on network.renderer.

DNS resolution

systemd-resolved is the Ubuntu system DNS. It runs on 127.0.0.53.

Use resolvectl to see the active name servers. The system gets its nameservers via netplan configs. You can hardcode the nameservers in /etc/systemd/resolved.conf. Set DNS=1.1.1.1, for example.

• Check if systemctl status systemd-resolved is running.
• Check if host www.cloudron.io 127.0.0.53 works.
• Check if systemd-resolved is the systemd DNS by checking if /etc/resolv.conf has nameserver 127.0.0.53

Domain issues & expiry

Check if the domain points to your server.

Check if your domain has expired. If the domain expired and you renew it, wait for the DNS records to return. Most registrars replace your DNS with parking pages during expiration. Some registrars won't revert your old DNS records. In such situations, add a DNS A record for my.example.com to point to the server's IP. Wait for the DNS to propagate and login to the dashboard. Go to Domains view and click the Sync DNS button to re-add Cloudron related DNS records.

To use an expired domain without renewing, edit your PC/Mac's /etc/hosts and add an entry (the old domain, not the new one) to point to the server.

/etc/hosts

1.2.3.4 my.example.com

• With this entry, visit https://my.example.com in your browser. You may need to purge the site from your browser's history to resolve HSTS certificate issues.

• Login and go to Domains view. Add the new domain.

• Change the dashboard domain to this new domain.

• Move all apps one by one from the old domain to the new domain by changing the location.

• Delete the old domain and remove the entry from /etc/hosts.

Failed upgrade

When the domain works and nginx runs, check the box logs at /home/yellowtent/platformdata/logs/box.log.

Ensure all migrations are up to date:

• Run /home/yellowtent/box/setup/start.sh on the server.
• Check systemctl status box. If not running, try systemctl restart box.

If errors persist, contact support.