documentation overhaul for DNS and domains topics

docs/admin/05.get_started/10.providers/05.registrar/ovh/manualdns.mdx

@@ -13,7 +13,7 @@ Click on the **DNS Zone** tab, then on **Add an entry**:
 
 ![OVH website screenshot](/img/providers/ovh_dns_zone.png?resize=800)
 
-Now you need to add the DNS redirections as specified by the [standard DNS zone configuration](/admin/get_started/post_install/dns_config)
+Now you need to add the DNS redirections as specified in the [DNS configuration page](/admin/domains/dns_configuration).
 
 Click on "Change in text format", keep the first four lines:
 
@@ -24,7 +24,7 @@ $TTL 3600
                          IN NS     ns104.ovh.net.
 ```
 
-then erase everything below, and replace it with the configuration generated by YunoHost as explained in [this page](/admin/get_started/post_install/dns_config).
+then erase everything below, and replace it with the configuration generated by YunoHost as explained in [this page](/admin/domains/dns_configuration).
 
 ### Dynamic IP
 

docs/admin/05.get_started/20.install_on/_configuration.mdx

@@ -52,13 +52,42 @@ If you want to create subdomains, do not forget to add them in the `hosts` file
 ```
 </details>
 
-This will be the domain used by your server's users to access the **authentication portal**. You can later add other domains, and change which one is the main domain if needed.
+This will be the domain used by your server's users to access the **authentication portal**. 
 
-- If you're new to self-hosting and do not already have a domain name, we recommend using a **.nohost.me** / **.noho.st** / **.ynh.fr** (e.g. `homersimpson.nohost.me`). Provided that it's not already taken, the domain will be configured automatically and you won't need any further configuration step. Please note that the downside is that you won't have full-control over the DNS configuration.
-- If you already own a domain name, you probably want to use it here. You will later need to configure DNS records as explained [here](/admin/get_started/post_install/dns_config).
+You should be presented with 3 options (reviewed [in details here](/admin/domains)):
+
+<details>
+  <summary>YunoHost's free domains</summary>
+
+  If you're new to self-hosting and do not already have a domain name, we recommend using the free domain provided by YunoHost.
+  You get multiple base domain choices:  `.nohost.me` / `.noho.st` / `.ynh.fr` for
+  which you must specify the subdomain you want to use (e.g. `homersimpson.nohost.me`).
+
+  Provided that it's not already taken, the domain will be configured automatically and you won't need any further configuration steps
+  (but as a downside you won't have full control over its DNS configuration).
+
+  [more details on YunoHost's free domains](/admin/domains/dns_nohost_me)
+</details>
+
+<details>
+  <summary>Your own domain</summary>
+
+  If you already own a domain name, you probably want to use it here. You will later need to configure DNS records as explained [here](/admin/domains/dns_configuration).
+
+  You can also configure a [subdomain](https://en.wikipedia.org/wiki/Subdomain) if your
+  main domain is already in use for other services.
+</details>
+
+<details>
+  <summary>Local domains</summary>
+
+  Because yes, you *have to* configure a domain name. And if none of the above options are
+  satisfying, you can set up a dummy domain such as `yolo.test` and tweak your **local** `/etc/hosts` file such that this dummy domain [points to the appropriate IP, as explained here](/admin/tutorials/domains/dns_local_network).
+</details>
 
 :::tip
-Yes, you *have to* configure a domain name. If you don't have any domain name and don't want a **.nohost.me** / **.noho.st** / **.ynh.fr** either, you can set up a dummy domain such as `yolo.test` and tweak your **local** `/etc/hosts` file such that this dummy domain [points to the appropriate IP, as explained here](/admin/tutorials/domains/dns_local_network).
+This choice can be modified later, by adding other domains, changing which one is the main domain,
+or set specific applications to run on a different domain.
 :::
 
 ### <FAIcon icon="fa-key"/> First user
@@ -74,7 +103,7 @@ Once the postinstall is done, you should be able to actually log in the web admi
 The diagnosis system is meant to provide an easy way to validate that all critical aspects of your server are properly configured - and guide you in how to fix issues. The diagnosis will run twice a day and send an alert if issues are detected.
 
 :::tip
-**Don't run away** ! The first time you run the diagnosis, it is quite expected to see a bunch of yellow/red alerts because you typically need to [configure DNS records](/admin/get_started/post_install/dns_config) (if not using a `.nohost.me`/`noho.st`/`ynh.fr` domain), add a swapfile if not enough ram as well as [port forwarding](/admin/get_started/post_install/port_forwarding) on your home's router.
+**Don't run away** ! The first time you run the diagnosis, it is quite expected to see a bunch of yellow/red alerts because you typically need to [configure DNS records](/admin/get_started/post_install/dns_config), add a swapfile if not enough ram as well as [port forwarding](/admin/get_started/post_install/port_forwarding) on your home's router.
 :::
 
 :::tip

docs/admin/05.get_started/40.post_install/20.dns_config.mdx

@@ -1,112 +1,14 @@
 ---
-title: DNS zone configuration
+title: Post-install domain configuration
 description: "Add a domain for easier access"
 ---
 
-DNS (domain name system) is a system that converts human-readable addresses
-(domain names) into machine-understandable addresses (IP). For your server to be
-easily accessible by human beings, and for some services like mail to work
-properly, DNS must be configured.
+Depending on the domain you picked during post-install you may have a few configuration
+steps left.
 
-If you're using an [automatic domain](/admin/tutorials/domains/dns_nohost_me) provided by the YunoHost Project, the configuration should be
-performed automatically. If you're using your own domain name (e.g. bought via
-a registrar), you should manually configure your domain on your registrar's
-interface.
+- If you picked one of YunoHost free domain (`nohost.me`, `noho.st`, `ynh.fr`) everything
+  is automatic and you should be good to go.
 
-## Recommended DNS configuration
+- If you picked a custom domain option you want to have a look at [DNS Configuration](/admin/domains/dns_configuration).
 
-NB: Examples here use the placeholder `your.domain.tld`, you have to replace it with your real domain, such as `www.yunohost.org`.
-
-YunoHost provides a recommended DNS configuration, available via:
-
-- the webadmin, in Domain > your.domain.tld > DNS configuration;
-- or the command line, `yunohost domain dns suggest your.domain.tld`
-
-For specific needs or specific setups, and if you know what you're doing, you
-might want or have to tweak these, or add additional ones (e.g. to handle
-subdomains).
-
-The recommended configuration typically looks like this:
-
-```bash
-#
-# Basic ipv4/ipv6 records
-#
-@ 3600 IN A 111.222.33.44
-* 3600 IN A 111.222.33.44
-
-# (If your server is IPv6 capable, there are some AAAA records)
-@ 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111
-* 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111
-
-#
-# XMPP
-#
-_xmpp-client._tcp 3600 IN SRV 0 5 5222 your.domain.tld.
-_xmpp-server._tcp 3600 IN SRV 0 5 5269 your.domain.tld.
-muc 3600 IN CNAME @
-pubsub 3600 IN CNAME @
-vjud 3600 IN CNAME @
-xmpp-upload 3600 IN CNAME @
-
-#
-# Mail (MX, SPF, DKIM and DMARC)
-#
-@ 3600 IN MX 10 your.domain.tld.
-@ 3600 IN TXT "v=spf1 a mx -all"
-mail._domainkey 3600 IN TXT "v=DKIM1; k=rsa; p=someHuuuuuuugeKey"
-_dmarc 3600 IN TXT "v=DMARC1; p=none"
-```
-
-Though it might be easier to understand it if displayed like this:
-
-| Type    | Name                   | Value                                                 |
-| :-----: | :--------------------: | :--------------------------------------------------:  |
-|  **A**  |   **@**                |  `111.222.333.444` (your IPv4)                        |
-|    A    |   *                    |  `111.222.333.444` (your IPv4)                        |
-|  AAAA   |   @                    |  `2222:444:8888:3333:bbbb:5555:3333:1111` (your IPv6) |
-|  AAAA   |   *                    |  `2222:444:8888:3333:bbbb:5555:3333:1111` (your IPv6) |
-| **SRV** | **_xmpp-client._tcp**  |  `0 5 5222 your.domain.tld.`                          |
-| **SRV** | **_xmpp-server._tcp**  |  `0 5 5269 your.domain.tld.`                          |
-|  CNAME  |   muc                  |  `@`                                                  |
-|  CNAME  |   pubsub               |  `@`                                                  |
-|  CNAME  |   vjud                 |  `@`                                                  |
-|  CNAME  |   xmpp-upload          |  `@`                                                  |
-| **MX**  | **@**                  |  `your.domain.tld.`     (and priority: 10)            |
-|   TXT   |   @                    |  `"v=spf1 a mx -all"`               |
-|   TXT   |  mail._domainkey       |  `"v=DKIM1; k=rsa; p=someHuuuuuuugeKey"`              |
-|   TXT   |  _dmarc                |  `"v=DMARC1; p=none"`                                 |
-
-### A few notes about this table
-
-- Not all these lines are absolutely necessary. For a minimal setup, you only need the records in bold.
-- The dot at the end of `your.domain.tld.` is important ;);
-- `@` corresponds to `your.domain.tld`, and e.g. `muc` corresponds to `muc.your.domain.tld`;
-- These are example values ! See your generated conf for the actual values you should use;
-- We recommend a [TTL](https://en.wikipedia.org/wiki/Time_to_live#DNS_records) of 3600 (1 hour). But you can use something else if you know what you're doing;
-- Don't put an IPv6 record if you're not sure IPv6 really works on your server! You might have issues with Let's Encrypt if it doesn't.
-- If you're using the domain provider Namecheap the SRV DNS entries are formatted as **Service**: `_xmpp-client` **Protocol**: `_tcp` **Priority**: `0` **Weight**: `5` **Port**: `5222` **Target**: `your.domain.tld`
-
-### Reverse DNS
-
-If your ISP or VPS provider let you define a [Reverse DNS
-lookup](https://en.wikipedia.org/wiki/Reverse_DNS_lookup) for your public IPv4
-and/or IPv6 addresses, you must configure it. It will prevent you to be marked as
-spam by anti-spam filters.
-
-**N.B.: the reverse DNS configuration happens on your Internet Service Provider or VPS provider. It is *not* handled by your domain's registrar.**
-
-If your public IPv4 address is `111.222.333.444` and your DNS
-domain is `domain.tld`, you should get following answer when using `nslookup`
-command tool:
-
-```bash
-nslookup 111.222.333.444
-444.333.222.111.in-addr.arpa    name = domain.tld.
-```
-
-The diagnosis system available in the webadmin performs this checks automatically (in section Email).
-
-### Dynamic IP
-
-If your global IP address is constantly changing, follow this [tutorial](/admin/tutorials/domains/dns_dynamicip).
+If you want to change the main domain you picked, have a look at [Domain](/admin/domains).

docs/admin/25.domains/dns_configuration.mdx

@@ -0,0 +1,167 @@
+---
+title: DNS Configuration
+---
+
+DNS (domain name system) is a system that converts human-readable addresses
+(domain names) into machine-understandable addresses (IP). For your server to be
+easily accessible by human beings, and for some services like mail to work
+properly, DNS must be configured.
+
+If you're using an [automatic domain](/admin/domains/dns_nohost_me) provided by the YunoHost Project, the configuration should be
+performed automatically. If you're using your own domain name (e.g. bought via
+a registrar), this page should explain how to manually configure your domain on your 
+registrar's interface.
+
+Note YunoHost supports the [automatic configuration of DNS records](/admin/domains/#dns-configuration) for some registrar.
+
+## A brief explanation of domain names 
+
+Because understanding domains can be tricky, it might be worth detailing how they work.
+
+A domain is a human-readable address made out of *labels* concatenated by dots.
+
+So if you take the domain name `www.yunohost.org` the usual convention is to break it down as:
+
+| domain             | description            |
+| :---------------:  | :--------------------: |
+| `.org`             | top-level domain       |
+| `yunohost.org`     | apex/root/bare domain  |
+| `www.yunohost.org` | subdomain              |
+
+However from [Wikipedia](https://en.wikipedia.org/wiki/Domain_name) we can learn:
+
+> *Domain names are organized in subordinate levels (subdomains) of the DNS root domain, which is nameless.*
+
+So in theory `yunohost.org` is a subdomain of `.org` but for convenience we usually
+talk about *subdomain* for any domain that has 2 levels after the top-level domain.
+This become even more confusing if you consider that some top-level domains have 2 labels
+(e.g. `.gouv.fr` or `.co.uk`).
+
+The wikipedia quote also mention the "DNS root domain" which is usually omitted but
+when not, is represented by a single dot at the end. This form is referred to as 
+"fully qualified domain name" (FQDN). With our previous example, `www.yunohost.org.` would be an FQDN. 
+This is good to remember because you usually need to specify an FQDN in your DNS records.
+
+## A brief explanation of DNS records.
+
+:::info
+DNS records must be managed through your registrar's interface (the vendor you rent your custom domain from).
+:::
+
+In the following explanations you can assume the examples in code blocks use the
+DNS [zone file](https://en.wikipedia.org/wiki/Zone_file) syntax. The lines we use
+have 5 columns separated by a whitespace. Those columns represent the different record's fields:
+
+| name | ttl | record class | record type | record data |
+| ---- | --- | ------------ | ----------- | ----------- |
+
+It's also good to be aware of the following:
+
+- We use placeholder values in the examples ! replace with the appropriate ones for your case.
+- We recommend a [TTL](https://en.wikipedia.org/wiki/Time_to_live#DNS_records) of 3600s (1 hour). But you can use something else if you know what you're doing.
+- Don't put an IPv6 record if you're not sure IPv6 really works on your server ! You might have issues with *Let's Encrypt* if it doesn't.
+- The `@` name corresponds to the origin, which is your apex domain name (like `mydomain.tld`)
+- Reminder that a domain specified in the data of the record **needs to end with a dot** (to be an FQDN as explained previously).
+
+## Minimal DNS configuration
+
+When registering a custom domain name through the YunoHost interface, this is the minimal
+required configuration to have it working.
+
+```autohotkey
+;; standard IPv4 record
+@ 3600 IN A 111.222.33.44
+
+;; if your server is IPv6 capable you can add an AAAA record
+@ 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111
+```
+
+However, this doesn't allow all features to work and you will notice warnings and errors
+when running the *Diagnosis* in the web interface.
+
+
+## Recommended DNS configuration
+
+YunoHost provides a recommended DNS configuration, available via:
+
+- the webadmin, in `Domains` > `{yourdomain.tld}` > `DNS`;
+- or the command line, `yunohost domain dns suggest yourdomain.tld`
+
+For specific needs or specific setups, and if you know what you're doing, you
+might want or have to tweak these, or add additional ones (e.g. to handle
+subdomains).
+
+The recommended configuration typically looks like this:
+
+```autohotkey
+;; standard IPv4 records
+@ 3600 IN A 111.222.33.44
+* 3600 IN A 111.222.33.44
+
+;; if your server is IPv6 capable you can add AAAA records
+@ 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111
+* 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111
+
+;; Mail (MX, SPF, DKIM and DMARC)
+@               3600 IN MX  10 mydomain.tld.
+@               3600 IN TXT "v=spf1 a mx -all"
+mail._domainkey 3600 IN TXT "v=DKIM1; k=rsa; p=someHuuuuuuugeKey"
+_dmarc          3600 IN TXT "v=DMARC1; p=none"
+```
+
+
+## Subdomains
+
+YunoHost allows the use of subdomains. If you rent a domain name `mydomain.com`,
+you can create a subdomain `blog.mydomain.com`.
+
+```autohotkey
+@      3600 IN A     111.222.33.44
+@      3600 IN AAAA  2222:444:8888:3333:bbbb:5555:3333:1111
+*      3600 IN CNAME mydomain.com.
+agenda 3600 IN CNAME mydomain.com.
+blog   3600 IN CNAME mydomain.com.
+rss    3600 IN CNAME mydomain.com.
+```
+
+The above allow you to access `agenda.mydomain.com`, `blog.mydomain.com` and `rss.mydomain.com` subdomains.
+
+However you might be in the position where your apex domain is already in use for another service
+(the `@ A` record is already in use).
+In that case you might want to have this DNS configuration instead:
+
+```autohotkey
+agenda 3600 IN A    XYZ.XYZ.XYZ.XYZ
+agenda 3600 IN AAAA 1234:1234:1234:FFAA:FFAA:FFAA:FFAA:AAFF
+blog   3600 IN A    XYZ.XYZ.XYZ.XYZ
+blog   3600 IN AAAA 1234:1234:1234:FFAA:FFAA:FFAA:FFAA:AAFF
+rss    3600 IN A    XYZ.XYZ.XYZ.XYZ
+rss    3600 IN AAAA 1234:1234:1234:FFAA:FFAA:FFAA:FFAA:AAFF
+```
+
+## Reverse DNS
+
+If your ISP or VPS provider let you define a [Reverse DNS
+lookup](https://en.wikipedia.org/wiki/Reverse_DNS_lookup) for your public IPv4
+and/or IPv6 addresses, you must configure it. It will prevent you to be marked as
+spam by anti-spam filters.
+
+:::note
+The reverse DNS configuration happens on your Internet Service Provider or VPS provider. It is NOT handled by your domain's registrar.
+:::
+
+If your public IPv4 address is `111.222.333.444` and your DNS
+domain is `mydomain.tld`, you should get following answer when using `nslookup`
+command tool:
+
+```bash
+nslookup 111.222.333.444
+444.333.222.111.in-addr.arpa    name = mydomain.tld.
+```
+
+From the web interface, you can run the *Diagnosis* and check in the *Email* section
+if reverse DNS is configured, and if not to which value it must be set to.
+
+## Dynamic IP
+
+If your global IP address is constantly changing, [follow this tutorial](/admin/tutorials/domains/dns_dynamicip).