Domains¶

Overview¶

The Domains view can be used to add a domain for use by Cloudron. Once added, apps can be installed as subdomains of the added domain. The Cloudron Email Server can also be enabled on a per-domain basis.

Cloudron integrates with various DNS service APIs to automate DNS setup. Using the API, Cloudron can also get Wildcard certificates via Let's Encrypt. This approach helps in hiding an app's domain from the Certificate Transparency Log.

If your DNS provider is not supported yet, we recommend using the Wildcard provider.

It is safe to add the same domain across multiple Cloudrons. This way, apps using the same top level domain can be installed on separate servers.

DNS providers¶

Bunny DNS¶

To get started:

Ensure that your domain is hosted on Bunny.
Once you domain is on Bunny, get the Access Key
In the Cloudron dashboard, choose Bunny from the drop down and provide the Access key.

Cloudflare DNS¶

To get started:

Ensure that your domain is hosted on Cloudflare. If your domain is not hosted on Cloudflare, you can follow the Cloudflare 101 guide.
Once your domain is on Cloudflare, get the Global API Key or API Token available in the profile section of your account.
Choose the Edit zone DNS template to create a token.
When using the API token, it must include the Zone:Read and DNS:Edit permission. The token only needs permission for the specific zone as shown below:
In the Cloudron dashboard, choose Cloudflare from the drop down and provide the API key.
In Cloudflare crypto configuration, set SSL to "Full SSL (Strict) mode". Users have often reported redirect loops without this setting.

Proxying

New DNS records are configured for proxying HTTP requests based on the Enable proxying for new DNS records checkbox. Please note that all your traffic is readably by Cloudflare when proxying is enabled. When enabled, we recommend also setting up Full SSL (Strict) mode.

Email and HTTP Proxy

If you use Cloudflare for your primary domain and enable Cloudron email for any domain, Cloudflare proxying must be disabled for the my subdomain. This is because Cloudflare will only proxy HTTP and not email protocol.

Subdomains with HTTPS Proxy

Cloudflare universal certificates only support one level of subdomain with HTTPS proxying on the free plan. See this forum thread for more information.

deSEC DNS¶

To get started:

Ensure that your domain is hosted on deSEC.
Once your domain is on deSEC DNS, create an token.
In the Cloudron dashboard, choose deSEC from the drop down and provide the token.

DigitalOcean DNS¶

To get started:

Ensure that your domain is hosted on DigitalOcean. If your domain is not hosted in DigitalOcean, you can follow this tutorial to point your domain's nameservers to DigitalOcean nameservers.
Once your domain is on DigitalOcean DNS, create an APIv2 token with read+write access.
In the Cloudron dashboard, choose DigitalOcean from the drop down and provide the API key.

DNSimple DNS¶

To get started:

Ensure that your domain is hosted on DNSimple. If your domain is not hosted in DNSimlple, you can follow these articles.
Once your domain is on DNSimple DNS, create an API token
In the Cloudron dashboard, choose DNSimple from the drop down and provide the API key.

Gandi LiveDNS¶

If you purchased a domain from Gandi, you can use Gandi LiveDNS for DNS integration.

To get started:

Ensure that your domain is using LiveDNS. Go the DNS Records page in Gandi to verify that you are using LiveDNS. Old domains might see a Switch to LiveDNS banner. If you see this, click on Gandi's DNS Records button and wait for 2-3 hours for Gandi to migrate the domain.
Next, create an LiveDNS API key from the security section. Choose Authentication options and scroll down to generate Personal Access Token (PAT). When generating the token, you can provide a specific domain name and select Manage domain name technical configurations permission.
In the Cloudron dashboard, choose Gandi LiveDNS from the drop down and provide the PAT.

GoDaddy¶

Restricted API access

As of 2024, access to parts of the Domains API is limited to accounts with 50 or domains.

If your domain is registered with GoDaddy, you can use Cloudron's GoDaddy DNS backend to manage the DNS.

To get started:

Create a GoDaddy API Key at their developer portal. When creating a new key select production environment.
In the Cloudron dashboard, choose GoDaddy from the drop down and provide the key and secret.

No Delete Record API

GoDaddy does not have an API to delete records. For this reason, Cloudron sets deleted records to 0.0.0.0.

Google Cloud DNS¶

To get started:

Ensure that your domain is hosted on Google Cloud DNS. You can move your existing domain to use the Cloud DNS by following this guide.

Google Domains

Google Domains is a different product than Google Cloud DNS. The above guide gives directions on how to make a Google Domains hosted domain use the Google Cloud DNS
Create a service account key in JSON format.
In the Cloudron dashboard, choose Google Cloud DNS from the drop down.

Hetzner DNS¶

To get started:

Ensure the domain is hosted using Hetzner DNS. If not, you can follow this guide.
Create a Hetzner API token.
In the Cloudron dashboard, choose Hetzner DNS from the drop down.

Robot vs KonsoleH

Cloudron only supports domains that have their name servers set to Robot (*.ns.hetzner.com). Domains registered via KonsoleH tend to have name severs like *.your-server.de. Please switch over to Robot name servers for the integration to work.

Linode DNS¶

To get started:

Ensure the domain is hosted using Linode DNS. If not, you can follow this guide to migrate an existing domain to use the service.
Create a Linode API token. The Personal Access Token must have Domains access. Set the Expiry to Never.
In the Cloudron dashboard, choose Linode from the dropdown.

Name.com DNS¶

If your domain is registered with name.com, you can use Cloudron's Name.com DNS backend to manage the DNS.

To get started:

Create a name.com API token
In the Cloudron dashboard, choose Name.com from the dropdown.

Namecheap DNS¶

If your domain is registered with Namecheap, you can use Cloudron's Namecheap DNS backend to manage the DNS.

To get started:

Enable API access for the Namecheap account (this is disabled by default). To do so, create an API key (Profile -> Tools) and whitelist your Cloudron's IP in the Namecheap dashboard.

Access error

It takes a few minutes for the IP whitelisting to take effect. If adding the domain in Cloudron gives an access error, wait a bit.

If you intend to enable Cloudron Email for this domain, select Custom MX in the MAIL SETTINGS and set the MX record to be my.example.com (i.e the primary domain). Once set, Cloudron will keep this record updated accordingly.
In the Cloudron dashboard, choose Namecheap from the drop down.

Netcup DNS¶

If your domain is registered with Netcup, you can use Cloudron's Netcup DNS backend to manage the DNS.

DNS updates are slow

On Netcup DNS updates take longer than on other providers. This means app installation or location may take a few minutes.

To get started:

Create an API Key and API Password for the Netcup account. To do so go to the Customer Control Panel and agree to the ToS. Then create both an API Key and the API Password.
In the Cloudron dashboard, choose Netcup from the drop down and enter your customer number, seen in the top of the customer control panel as well as the API key and password.

OVH DNS¶

To get started:

Create an Application key, Application secret and Consumer Key by following the docs at OVHCloud Help.
API Keys can be created with a minimal scope:

GET /domain/zone/{zone Name}/record
POST /domain/zone/{zone Name}/record
PUT /domain/zone/{zone Name}/record/*
DELETE /domain/zone/{zone Name}/record/*
GET /domain/zone/{zone Name}/record/*
POST /domain/zone/{zone Name}/refresh

In the Cloudron dashboard, choose OVH from the drop down and enter the Application key, Application secret & Consumer Key.

Porkbun DNS¶

To get started:

Create an API Key and API Secret in the Porkbun dashboard.
Ensure API ACCESS is enabled for the domain. Note that API access to a domain is disabled by default, so this is a necessary step.
In the Cloudron dashboard, choose Porkbun from the drop down and enter the API key and API secret.

Route53 DNS¶

To get started:

Ensure the domain is hosted using AWS Route53. If not, you can follow this guide to migrate an existing domain to use the service.
AWS has two forms of security credentials - root and IAM. When using root credentials on AWS, follow the instructions here to create access keys. When using IAM, follow the instructions here to create a user and use the following policy to give the user access to the domain. The <hosted zone id> below must be replaced with the zone's id which is available from the Route53 console.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "route53:*",
            "Resource": [
                "arn:aws:route53:::hostedzone/<hosted zone id>"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "route53:ListHostedZones",
                "route53:listHostedZonesByName",
                "route53:GetHostedZone",
                "route53:GetChange",
                "route53:ChangeResourceRecordSets"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

In the Cloudron dashboard, choose AWS Route53 from the drop down.

Not available in AMI

This feature is disabled in AWS Marketplace AMI. AWS Marketplace Policy disallows AMIs from requesting IAM credentials from users to access Route53 hosted domains. Please use the Wildcard or Manual provider instead.

Vultr DNS¶

To get started:

Ensure the domain is hosted using Vultr DNS. If not, you can follow this guide to migrate an existing domain to use the service.
Create a Vultr API token. Add the server's IP in the Access Control section.
In the Cloudron dashboard, choose Vultr from the dropdown.

Wildcard DNS¶

If your domain is not hosted on any of the DNS providers supported by Cloudron, you can use the Wildcard DNS backend.

To get started:

Add a DNS A record with name *.example.com to point to your server's IP.

Wildcard entry has lower precedence

In DNS, a wildcard entry has lower precedence to subdomains that are explicitly defined. This means that if you already have a blog.example.com pointing to a different IP address, then it will be unaffected by the addition of this wildcard entry.

(Optional) Add a DNS A record with name example.com to point to your server's IP. This is required only if you intend to host an app on the naked/bare domain (example.com) on the Cloudron.
In the Cloudron dashboard, choose Wildcard from the dropdown.
For sending email, Cloudron requires DKIM and SPF records to be setup as well. These records will be displayed in the UI after installation and have to be setup manually.

Let's Encrypt integration

Cloudron will use Let's Encrypt HTTP validation to procure certificates for apps. For this reason, you must open port 80 of your server when using the Wildcard provider.

Manual DNS¶

If your domain is not hosted on any of the DNS providers supported by Cloudron, and you cannot use the Wildcard DNS provider, then you can use the Manual DNS provider.

With the manual DNS provider, you have to setup DNS records prior to installing Cloudron and also prior to installing each app. App installation will not succeed until DNS records are setup correctly.

If you are attempting to finish Cloudron setup:

Set the my subdomain to the server's public IP
Choose Manual from the DNS provider drop down
For sending email, Cloudron requires DKIM and SPF records to be setup as well. These records will be displayed in the UI after installation and have to be setup manually.
Remember to setup A records for subdomains to the server's public IP and then install apps.

Let's Encrypt integration

Cloudron will use Let's Encrypt HTTP validation to procure certificates for apps. For this reason, you must open port 80 of your server when using the Wildcard provider.

No-op DNS¶

The No-op DNS backend disables Cloudron's DNS functionality and is intended to be used for testing and development.

When using other DNS backends, Cloudron will setup the DNS automatically and also check if the DNS changes have propagated. This prevents the user from hitting name resolution (NXDOMAIN) errors. When using the No-op backend, the setup and checks are disabled and you are on your own to ensure that names are getting resolved correctly.

Zone Name¶

The DNS Zone Name is the domain name that is being managed by the DNS provider. By default, this value is the top level domain like example.com. If the domain and subdomain are managed by different DNS providers, then provide the zone name here.

For example, example.com might have been purchased at GoDaddy. You can delegate a subdomain like internal.example.com to DigitalOcean by adding it in DigitalOcean and setting the NS records of internal.example.com to DigitalOcean DNS. In such a situation, if you use cloudron.internal.example.com as the primary domain for Cloudron, the the zone name must be set to internal.example.com.

Well Known Locations¶

A well-known URI is a Uniform Resource Identifier for a URL path prefixes that start with /.well-known/. They are implemented in webservers so that requests to the servers for well-known services or information are available at URLs consistent well-known locations across servers. See RFC 8615 for more information.

You can edit well known locations in the Domains view:

Clicking the button will open up a dialog where you can fill up well known locations:

Matrix server location¶

The matrix hostname is the domain name and port on which the Matrix server is running. When set, Cloudron will respond to two well-known URIs:

The https://{domain}/.well-known/matrix/server end point. This is required for federation to work. Note that Cloudron can respond to this end point only when an app is installed on the bare domain.
The https://{domain}/.well-known/matrix/client end point. This is required by clients to discover the matrix servers.

Specify port 443 explicitly

The default matrix server port is 8448. However, the Synapse app on Cloudron uses port 443. For this reason, you must specify the port explicity, like matrix.domain.com:443.

Requires app on bare domain

In the above example, an app must be installed on the bare domain https://cloudron.club for Cloudron to be able to respond to well known queries.

Mastodon server location¶

The mastodon hostname is the domain name on which the mastodon server is running. When set, Cloudron will respond to requests to the https://{domain}/.well-known/host-meta end point. This is required for federation to work. Cloudron can respond to this end point only when an app is installed on the bare domain.

Requires app on bare domain

In the above example, an app must be installed on the bare domain https://cloudron.club for Cloudron to be able to respond to well known queries.

Jitsi location¶

The Jitsi hostname is the domain name on which the jitsi server is running. When set, Cloudron will respond to requests to the https://{domain}/.well-known/matrix/client end point as suggested here.

Requires app on bare domain

In the above example, an app must be installed on the bare domain https://cloudron.space for Cloudron to be able to respond to well known queries.

Dashboard domain¶

The Cloudron dashboard/admin UI is located at the my subdomain of the Cloudron's primary domain. The my subdomain is hardcoded and cannot be changed. However, the primary domain can be changed from the Domains view.

Select the domain to move the dashboard into and click Change Domain. In a few minutes, you should be redirected to the new location.

Changing the primary domain has the following implications:

The dashboard is moved to my.newprimarydomain.com. Please update any browser bookmarks accordingly.
Scripts using the Cloudron API must be updated to use the new dashboard domain.
Email notifications from the server will now be sent as no-reply@newprimarydomain.com.
The mail server location is unchanged when you change the dashboard domain.
The old domain's my DNS record is not removed by Cloudron. This is because the mail server location defaults to the dashboard domain at installation time. If you end up changing the mail server location as well, the my subdomain of the old domain can be safely removed from the DNS.

Unreachable dashboard

If your dashboard is unreachable, see the troubleshooting section

Sync DNS¶

If you accidentally deleted DNS records or are switching DNS providers, you can restore them using the Sync DNS button in the Domains view. Note that Cloudron can only restore DNS records that are in use by Cloudron and not records that were externally created.

Autodiscover¶

DAV¶

RFC 6764 provides a way for locating services like CalDAV and CardDAV of a domain. For the moment, you can current add DNS entries manually to make these services discoverable.

See this tutorial for the required entries.

Email¶

See Email autodiscovery for more information.