Domains, DNS conf, and certificate

YunoHost allows you to manage and serve several domains on the same server. For instance, you can host a blog and Nextcloud on a first domain, and a web mail client on a second domain Each domain is automatically configured to handle web services, mail services and XMPP services.

Domains can be managed in the 'Domain' section of the webadmin, or through the yunohost domain category of the command line.

Each time you add a domain, it is expected that you bought it (or own it) on a domain registrar, so you can manage the DNS configuration. The exception is the, and domains which are paid for by the YunoHost Project, and can be directly integrated with YunoHost thanks to an automated dynDNS setup. To limit costs and abuses, each instance may only have one of these domains setup at any given time, however you can add as many sub-domains of it as you wish. For example, if you choose you can later add the domains or or any other sub-domain you may need.

The domain chosen during the initial configuration (post-install) is defined as the main domain of the server : this is where the SSO and the web admin interface will be available. The main domain can later be changed through the web admin in Domains > (the domain) > Set default, or with the command line yunohost tools maindomain.

Finally, take note that, in the context of YunoHost, there is no hierarchy between the domains it knows. In the previous example, you may add a third domain - but it would be considered as a domain independent of

Non-latin characters

If your domain has special, non-latin characters, you need to use its internationalized version through Punycode. You can use this converter, and use the converted domain name in your YunoHost configuration.

Local domains

Starting from YunoHost v4.3, domains ending by .local are fully supported, in addition to the default yunohost.local. They do not use the DNS protocol, but the mDNS one (also known as Zeroconf, Bonjour), which allows them to be published with no specific configuration but exclusively on your local network or VPN. Their use is this especially suitable when you do not want one of your apps to be available on the Internet.

mDNS protocol does not allow for subdomains to be created. So domain.local will work, while sub.domain.local is not possible.

Yunomdns service takes care of publishing your .local domains on your network. It has a configuration file, /etc/yunohost/mdns.yml, which allows you to choose which domains are published, and on which network interfaces. This file is automatically regenerated whenever you add or delete a .local domain.

The service will always try to publish yunohost.local. If you have multiple YunoHost servers on your network, try yunohost-2.local, and so on. The number may change depending on which server starts first, so do not rely on it to use actual apps and create your own domains.

Unfortunately, Android devices before version 12 (released in 2021) do not seem to be listening to mDNS protocol. To be able to reach .local domains on your Android devices, you will have to add in their DNS settings your YunoHost server's local IP address.

DNS configuration

DNS (Domain Name System) is a system that allows computers from around the world to translate human-readable domain names (such as to machine-understandable adresses called IP addresses (such as For this translation (and other features) to work, you must carefully configure DNS records.

YunoHost can generate a recommended DNS configuration for each domain, including elements needed for mail and XMPP. The recommended DNS configuration is available in the webadmin via Domain > (the domain) > DNS configuration, or with the command yunohost domain dns-conf the.domain.tld.

SSL/HTTPS certificates

Another important aspect of domain configuration is the SSL/HTTPS certificate. YunoHost is integrated with Let's Encrypt, so once your server is correctly reachable from anybody on the internet through the domain name, the administrator can request a Let's Encrypt certificate. See the documentation about certificates for more information.

Subpaths vs. individual domains per apps

In the context of YunoHost, it is quite common to have a single (or a few) domains on which several apps are installed in "subpaths", so that you end up with something like this:
     ├── /blog  : Wordpress (a blog)
     ├── /cloud : Nextcloud (a cloud service)
     ├── /rss   : TinyTiny RSS (a RSS reader)
     ├── /wiki  : DokuWiki (a wiki)

Alternatively, you may choose to install each (or some) apps on a dedicated domain. Beyond the aesthetic, using sub-domains instead of sub-paths allows the possibility to move a service to another server more easily. Also, some applications may need an entire domain dedicated to them, for technical reasons. The disadvantage is that you have to add a new domain each time, and therefore potentially configure additional DNS records, restart the diagnostics and install a new Let's Encrypt certificate.

This might look prettier for end users, but is generally considered more complicated and less efficient in the context of YunoHost, since you need to add a new domain each time. Nevertheless, some apps might need an entire domain dedicated to them, for technical reasons.

If all apps from the previous example were installed on a separate domain, this would give something like this:  : Wordpress (a blog) : Nextcloud (a cloud service)   : TinyTiny RSS (a RSS reader)  : DokuWiki (a wiki)

Many applications integrate a functionality that allows you to change the URL of your application. This choice between subpath and subdomain can be reversed in some cases via a simple manipulation in the administration interface.

Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to suggest changes.