Skip to content

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

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.

DNS and HTTP Proxy

Cloudron configures Cloudflare to proxy only the DNS. If you change this setting in Cloudflare to proxy HTTP traffic as well, be sure to use the 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.

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.

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

  • In the Cloudron dashboard, choose Gandi LiveDNS from the drop down and provide the API key.

GoDaddy

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.

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.

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.

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.

The default matrix server port is 8448. The synapse app on Cloudron uses port 443 instead. For this reason, it is important to explicitly provide the port number as 443 like below:

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

Mail clients like Outlook and Thunderbird can use the autoconfig DNS records to configure the mail accounts. See Thunderbird Autoconfiguration docs and Outlook Autodiscover docs for more information.