Improve domain page

pages/01.administer/06.admin_guide/06.domains/domains.md

@@ -1,31 +1,72 @@
 ---
-title: Domains, DNS conf, and certificate
+title: Domains
 template: docs
 taxonomy:
     category: docs
 routes:
   default: '/domains'
+shortcode-ui:
+  theme:
+    tabs: lite
 ---
 
-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 `yolo.com`, and a web mail client on a second domain `swag.nohost.me`. Each domain is automatically configured to handle web services, mail services and XMPP services.
+DNS (Domain Name System) is a system that allows computers from around the world to translate human-readable domain names (such as `yolo.com`) to machine-understandable adresses called IP addresses (such as `11.22.33.44`). For this translation (and other features) to work, you must carefully configure DNS records.
+
+YunoHost allows you to manage and serve several domains on the same server with the same public ip. For instance, you can host a blog and Nextcloud on a first domain `yolo.com`, and a web mail client on a second domain `swag.nohost.me`. 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](/dns_config). The exception is the [`.nohost.me`, `.noho.st` and `ynh.fr` domains](/dns_nohost_me) 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 `example.noho.st` you can later add the domains `video.example.noho.st` or `www.example.ynh.noho.st` or any other sub-domain you may need.
+![A screenshot of the webadmin domain interface with an "Add domain" button and a list of domains](image://webadmin_domain.png)
 
-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`.
+## 3 types of domains
 
-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 `foo.yolo.com` - but it would be considered as a domain independent of `yolo.com`.
+[ui-tabs position="top-left" active="0" theme="lite"]
+[ui-tab title="Yunohost's domains (the free and easy way)"]
 
-## Non-latin characters
+In order to make self-hosting as accessible as possible, the YunoHost Project provides a *free* and *automatically configured* domain name service. By using this service, you won't have to [configure DNS records](/dns_config) yourself, which can be tedious and technical.
 
-If your domain has special, non-latin characters, you need to use its [internationalized version](https://en.wikipedia.org/wiki/Internationalized_domain_name) through [Punycode](https://en.wikipedia.org/wiki/Punycode). You can use [this converter](https://www.charset.org/punycode), and use the converted domain name in your YunoHost configuration. 
+The following (sub)domains are offered:
+- `whateveryouwant.nohost.me`;
+- `whateveryouwant.noho.st`;
+- `whateveryouwant.ynh.fr`.
 
-## Local domains
+In more, YunoHost uses an integrated dynamic DNS mechanism, so your server can stay reachable even if your public IP change.
+
+To get one of this domain you simply need to choose `I don't have a domaine name…` during the initial configuration (postinstall) or on the `Add domain` page.
+
+![Here a screenshot of the "Add domain" page where you can choose "I don't have a domain name"](image://webadmin_dyndns.png)
+
+! To limit resources 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 `example.noho.st` you can later add the domains `video.example.noho.st` or `www.example.ynh.noho.st` or any other sub-domain you may need. In this case you need to select `I already have a domain name`.
+
+!! You have to keep a backup archive of the config file of your server if you want to be able to restore your server with this domain name without [asking help of YunoHost team to recover access on it](https://forum.yunohost.org/t/nohost-domain-recovery-suppression-de-domaine-en-nohost-me-noho-st-et-ynh-fr/442).
+
+[More information on this domains](/dns_nohost_me)
+
+[/ui-tab]
+[ui-tab title="Your own domains"]
+Having your own domain brings several advantages:
+
+ * more control and autonomy
+ * simpler domain name (for example directly in .net or .org)
+
+However, you have to pay for it each year (about 15€/year) and you have to do some extra configuration to [setup a correct DNS zone](/dns_config). Our diagnosis tool can trigger alert to help you to do this configuration.
+
+If you already have your own domain, you can simply click "I already have a domain name…". If you don't, in order to simplify and automate the DNS configuration, we suggest you to buy it from a [registrar whose API is supported by YunoHost](/providers/registrar). 
+
+![Here a screenshot of the "Add domain" page where you can choose "I already have a domain name"](image://webadmin_domain_owndomain.png)
+
+
+[Know more on DNS zone configuration](/dns_config)
+
+
+[/ui-tab]
+[ui-tab title="Local domains (only reachable in your local network)"]
 
 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.
+Their use is this especially suitable when you do not need your apps to be available on the Internet.
+
+![Here a screenshot of the "Add domain" page where you can choose "I already have a domain name" and setup your domain ending by .local](image://webadmin_domain_local.png)
 
 !!!! mDNS protocol does not allow for subdomains to be created. So `domain.local` will work, while `sub.domain.local` is not possible.
 
@@ -39,11 +80,19 @@ The number may change depending on which server starts first, so do not rely on
 ! 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 `yolo.com`) to machine-understandable adresses called IP addresses (such as `11.22.33.44`). For this translation (and other features) to work, you must carefully configure DNS records. 
+[/ui-tab]
+[/ui-tabs]
+
+## The main domain
+The domain chosen during the initial configuration (post-install) is defined as the main (or default) domain of the server : this is where [the user portal (SSO)](/users) 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`.
+
+More technically, the main domain is also used as hostname by SMTP protocol to send email (EHLO) and determine which value should be configured in the reverse DNS bind to your public IP. If this 2 values are mis-configured, the diagnosis tool will trigger you an alert.
+
+## About Non-latin characters
+
+If your domain has special, non-latin characters, it will be transformed by YunoHost into its [internationalized version](https://en.wikipedia.org/wiki/Internationalized_domain_name) through [Punycode](https://en.wikipedia.org/wiki/Punycode). So when you use the command line, you have to use the punycode format return for example by `yunohost domain list`.
 
-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