[IMP] install/maintain: new improved doc about domain names

task-id 2680490

closes odoo/documentation#1648

X-original-commit: d22f95362a
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
Signed-off-by: Castillo Jonathan (jcs) <jcs@odoo.com>

content/administration/maintain.rst

@@ -6,6 +6,7 @@ Maintain
 
 .. toctree::
 
+    maintain/domain_names
     maintain/update
     maintain/enterprise
     maintain/hosting_changes

content/administration/maintain/domain_names.rst

@@ -0,0 +1,326 @@
+============
+Domain names
+============
+
+A **domain name** works as an address for your website. It makes the Internet much more accessible
+as it allows users to type a meaningful web address, such as ``www.odoo.com``, rather than its
+server's IP address with a series of numbers.
+
+You can use a custom domain name to access your Odoo database and websites:
+
+- By :ref:`registering a free domain name with Odoo <domain-name/odoo-register>` (for Odoo Online
+  databases)
+- By :ref:`configuring a custom domain that you already own <domain-name/existing>`.
+
+.. note::
+   Odoo Online and Odoo.sh databases, including their websites, use by default a subdomain of
+   ``odoo.com`` for both the URL and the emails (e.g., ``https://example.odoo.com``).
+
+.. important::
+   Odoo offers a :ref:`free custom domain name <domain-name/odoo-register>` to all Odoo Online 
+   databases for one year. Visitors can then access your website with an address such as
+   ``www.example.com`` rather than the default ``example.odoo.com``.
+
+.. _domain-name/about:
+
+About domain names
+==================
+
+Having a **good domain name** is as important to your branding as the name of your business or
+organization as it is the first thing your visitors will notice. We recommend you keep them *simple,
+short, easy to remember and spell*.
+
+A **subdomain** is a domain that is a part of another domain. It often refers to the additional part
+that comes before the main domain name. Traditionally, most websites use the ``www.`` subdomain,
+but any string of letters can be used as well. You can use subdomains to direct your visitors to
+other websites than your main website or to specific pages (e.g., ``experience.odoo.com`` points to
+a specific page.)
+
+All domain names are referenced in the **Domain Name System**, or **DNS**, which works as a giant
+directory for the Internet. There are many DNS servers, so any modification to the DNS can take up
+to 72 hours to propagate worldwide on all servers.
+
+.. _domain-name/odoo-register:
+
+Register a free domain name with Odoo
+=====================================
+
+You can register a domain name for your Odoo Online database directly from Odoo Website or your
+database manager.
+
+.. important::
+   - Your domain name is **free for one year** if you register it with Odoo!
+   - The domain name is registered with `Gandi <https://www.gandi.net/>`_, the domain name
+     registrar.
+   - You are the owner of the domain name and can use it for other purposes.
+   - Odoo manages payment and technical support for you.
+
+To do so, go to :menuselection:`Website --> Go to website --> Promote --> Domain Name`.
+Alternatively, open your `database manager <https://www.odoo.com/my/databases>`_, click on the
+*settings* button next to your database, then on *Domain names*.
+
+.. image:: domain_names/register-promote.png
+   :align: center
+   :alt: Clicking on Domain Names from an Odoo website
+
+Search for the domain name of your choice to check its availability, then select the one you want to
+register for your website.
+
+.. image:: domain_names/register-search.png
+   :align: center
+   :alt: The search of the domain name example.com shows which associated domains are available.
+
+Next, fill in the form with your information to become the domain name owner.
+
+Your domain name is directly linked to your database, but you still have to :ref:`map your domain
+name with your website <domain-name/website-map>`.
+
+.. note::
+   - Free domain names are also available for free Odoo Online databases (if you installed one app
+     only, for example). In this case, Odoo reviews your request and your website to avoid abuse.
+     This process may take up to three days.
+   - This is not available for Odoo.sh databases yet.
+
+.. _domain-name/odoo-manage:
+
+Manage your domain name registered with Odoo
+--------------------------------------------
+
+To manage the DNS records of your domain name registered with Odoo or to visualize the contacts
+associated with it, open your `database manager <https://www.odoo.com/my/databases>`_, click on the
+*settings* button next to your database, on *Domain names*, and then on *Contacts* or *DNS*.
+
+.. image:: domain_names/manage.png
+   :align: center
+   :alt: Management of the domain names linked to an Odoo database
+
+.. note::
+   Please `submit a support ticket <https://www.odoo.com/help>`_ if you need further assistance to
+   manage your domain name.
+
+.. _domain-name/existing:
+
+Configure your existing domain name
+===================================
+
+If you already own a domain name, you can use it to point to your website.
+
+To avoid any issue with the :ref:`SSL certificate validation <domain-name/ssl>`, we highly recommend
+that you proceed with the following actions in this order:
+
+#. :ref:`Add a CNAME record <domain-name/cname>` on your domain name's DNS zone.
+#. :ref:`Map your domain name with your Odoo database <domain-name/db-map>`.
+#. :ref:`Map your domain name with your Odoo website <domain-name/website-map>`.
+
+.. _domain-name/cname:
+
+Add a CNAME record
+------------------
+
+A **CNAME record** is a type of DNS record that points to the IP address of another website rather
+than to directly to an IP address.
+
+You need a CNAME record that points to your Odoo database. The requirements are detailed in your
+database manager.
+
+.. tabs::
+
+   .. group-tab:: Odoo Online
+
+      The target address is the current address of your database, as defined at its creation (e.g.,
+      ``example.odoo.com``)
+
+   .. group-tab:: Odoo.sh
+
+      Your project's main address is defined in :menuselection:`Settings --> Project Name`.
+
+      If you want to target a specific branch (production, staging or development), go to
+      :menuselection:`Branches --> select your branch --> Settings --> Custom domains`, and click on
+      *How to set up my domain?*. A message indicates which address your CNAME record should target.
+
+#. Open your domain name's manager dashboard.
+#. Open the **DNS zone** management page for the domain name you want to configure.
+#. Create a **CNAME record** pointing to the address of your database.
+
+While Odoo suggests creating a CNAME record for your ``www.`` subdomain (``www.example.com``, you
+can of course use any domain name of your choice, with any subdomain (e.g.,
+``anything.example.com``).
+
+.. example::
+   You own the domain name ``example.com``, and you have an Odoo Online database at the address
+   ``example.odoo.com``. You want to access your Odoo database primarily with the domain
+   ``www.example.com`` but also with the :ref:`naked domain <domain-name/naked-domain>`
+   ``example.com``.
+
+   To do so, you create a CNAME record for the ``www`` subdomain, with ``example.odoo.com`` as the
+   target. The DNS zone manager generates the following rule and adds it to your DNS zone: ``www IN
+   CNAME example.odoo.com.``
+
+   You also create a redirection from ``example.com`` to ``wwww.example.com``.
+
+   Your new DNS records are propagated to all DNS servers.
+
+.. note::
+   Here are some specific guidelines to create a CNAME record:
+
+   - `GoDaddy <https://www.godaddy.com/help/add-a-cname-record-19236>`_
+   - `Namecheap <https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain>`_
+   - `OVH <https://docs.ovh.com/us/en/domains/web_hosting_how_to_edit_my_dns_zone/#add-a-new-dns-record>`_
+   - `CloudFlare <https://support.cloudflare.com/hc/en-us/articles/360019093151>`_
+   - `Google Domains <https://support.google.com/domains/answer/3290350?hl=en>`_
+
+.. _domain-name/naked-domain:
+
+Naked domain
+~~~~~~~~~~~~
+
+A **naked domain** is a domain name that doesn't have any subdomain at the beginning of the address
+(e.g., ``odoo.com`` instead of ``www.odoo.com``).
+
+You may want your naked domain to redirect to your website as some visitors may not type the full
+domain name to access your website.
+
+#. Open your domain name's manager dashboard.
+#. Create a **redirection** from the naked domain (``example.com``) to your main domain name
+   (``www.example.com``)
+
+.. note::
+   Depending on your domain name registrar, this redirection may be already pre-configured.
+
+.. _domain-name/db-map:
+
+Map your domain name with your Odoo database
+--------------------------------------------
+
+.. tabs::
+
+   .. group-tab:: Odoo Online
+
+      Open your `database manager <https://www.odoo.com/my/databases>`_, click on the *settings*
+      button next to your database, on *Domain names*, and then on *Use my own domain* at the bottom
+      of the right column.
+
+      Type the domain name you want to add to this database, then click on *Verify* to check if the
+      the CNAME record is correctly configured. Once done, click on *I confirm, it's done*.
+
+      .. image:: domain_names/online-map.png
+         :align: center
+         :alt: Verification of the CNAME records of a domain name before mapping it with a database
+
+   .. group-tab:: Odoo.sh
+
+      Go to :menuselection:`Branches --> select your branch --> Settings --> Custom domains`, type
+      the domain name you want to add to this database, then click on *Add domain*.
+
+      .. image:: domain_names/odoo-sh-map.png
+         :align: center
+         :alt: Mapping a domain name with an Odoo.sh branch
+
+      .. seealso::
+         - :ref:`Odoo.sh branches: settings tab <odoosh-gettingstarted-branches-tabs-settings>`
+
+.. warning::
+   Make sure to :ref:`add a CNAME record <domain-name/cname>` to your domain name's DNS **before**
+   mapping your domain name with your Odoo database.
+
+   Failing to do so may impede the validation of the :ref:`SSL certificate <domain-name/ssl>` and
+   would result in a *certificate name mismatch* error. This is often displayed by web browsers as a
+   warning such as *"Your connection is not private"*.
+
+   If this is the case and you have added the domain name to your database's settings less than five
+   days ago, wait 24 hours as the validation may still happen. Otherwise, please `submit a support
+   ticket <https://www.odoo.com/help>`_ including screenshots of your CNAME records.
+
+.. _domain-name/ssl:
+
+SSL encryption (HTTPS protocol)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**SSL encryption** is an encryption-based Internet security protocol. It allows your visitors to
+navigate your website through a secure connection, which appears as an ``https://`` protocol at the
+beginning of your web address, rather than a non-secure ``http://`` protocol.
+
+Odoo generates a separate SSL certificate for each domain :ref:`mapped in the database manager
+<domain-name/db-map>`, using integration with `Let's Encrypt Certificate Authority and ACME protocol
+<https://letsencrypt.org/how-it-works/>`_.
+
+.. note::
+   - The certificate generation may take up to 24h.
+   - Several attempts to validate your certificate are made during the five days following the
+     moment you add your domain name in your database's settings.
+   - If you already use another service, you can keep using it or simply change for Odoo.
+
+.. _domain-name/web-base-url:
+
+Web base URL of a database
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+   If you have Odoo Website, you can disregard this part and directly :ref:`map your domain name
+   with your website <domain-name/website-map>`.
+
+The **web base URL** of a database, or **root URL** affects your main website address and all the
+links sent to your customers (e.g., quotations, portal links, etc.).
+
+To configure it, access your Odoo database with your custom address, then log in as an administrator
+of your database (any user in the *Settings* group) from the login screen.
+
+.. warning::
+   Connecting to your database with the original Odoo subdomain address (e.g., ``example.odoo.com``
+   also updates the web base URL of your database. See below to prevent these automatic updates.
+
+Alternatively, you can do it manually. To do so, activate the :ref:`developer mode
+<developer-mode>`, then go to :menuselection:`Settings --> Technical --> System Parameters`.
+
+Find the key called ``web.base.url`` (or create it if it does not exist) and enter the full address
+of your website as value, such as ``https://www.example.com``.
+
+.. note::
+   The URL must include the protocol ``https://`` (or ``http://``) and must not end with a slash
+   (``/``).
+
+To prevent the automatic update of the web base URL when an administrator logs in the database, you
+can create the following System Parameter:
+
+- key: ``web.base.url.freeze``
+- value: ``True``
+
+.. _domain-name/website-map:
+
+Map your domain name with your website
+======================================
+
+Mapping your domain name to your website isn't the same as mapping it with your database:
+
+- It defines your domain name as the main one for your website, helping search engines to index your
+  website properly.
+- It defines your domain name as the base URL for your database, including the portal links sent by
+  email to your customers.
+- If you have multiple websites, it maps your domain name with the appropriate website.
+
+Go to :menuselection:`Website --> Configuration --> Settings --> Website Info`. If you have multiple
+websites, select the one you want to configure.
+
+In the **Domain** field, fill in the web address of your website (e.g., ``https://www.example.com``)
+and click on *Save*.
+
+.. image:: domain_names/website-settings.png
+   :align: center
+   :alt: Configuring https://www.example.com as the Domain of the website
+
+.. warning::
+   Mapping your domain name with your Odoo website prevents Google from indexing both your custom
+   domain name ``www.example.com`` and your original odoo database address ``example.odoo.com``.
+
+   If both addresses are already indexed, it may take some time before Google removes the indexation
+   of the second address. You may also try using the `Google Search Console
+   <https://search.google.com/search-console/welcome>`_ to fix this.
+
+.. note::
+   If you have multiple websites and companies on your database, make sure that you select the
+   right **Company** in the website settings, next to the **Domain** settings. Doing so indicates
+   Odoo which URL to use as the :ref:`base URL <domain-name/web-base-url>` according to the company
+   in use.
+
+.. seealso::
+  - :doc:`/applications/general/email_communication/email_servers`

content/administration/maintain/online.rst

@@ -95,7 +95,7 @@ Domains
 Configure custom domains to access the database via another URL.
 
 .. seealso::
-   - :doc:`/applications/websites/website/publish/domain_name`
+   - :doc:`domain_names`
 
 .. _online/tags:
 

content/applications/general/email_communication/email_template.rst

@@ -43,7 +43,7 @@ When using Odoo, multiple events trigger the sending of automated emails. These
 as transactional emails and sometimes contain links pointing to your Odoo database.
 
 By default, links generated by the database use the dynamic web.base.url key defined in the system
-parameters. More information about this :ref:`parameter <app-website/web_base_url>`.
+parameters. More information about this :ref:`parameter <domain-name/web-base-url>`.
 
 If the website application isn't installed, the web.base.url key will always be the default 
 parameter used to generate all the links.
@@ -69,7 +69,7 @@ link established with the website from which the order was made. As a result, th
 the sales orders uses the domain name defined for the corresponding website to generate the links.
 
 For more information about how to configure your domains, we invite you to check :doc:`our domain name 
-documentation </applications/websites/website/publish/domain_name>`.
+documentation </administration/maintain/domain_names>`.
 
 Updating translations within email templates
 ********************************************

content/applications/websites/ecommerce.rst

@@ -10,6 +10,11 @@ eCommerce
 Run a modern open-source online store with Odoo eCommerce. Learn how to sell online, promote
 products and increase your average cart sizes.
 
+.. important::
+   Odoo offers a :ref:`free custom domain name <domain-name/odoo-register>` to all Odoo Online 
+   databases for one year. Visitors can then access your website with an address such as
+   ``www.example.com`` rather than the default ``example.odoo.com``.
+
 .. seealso::
    - `Odoo Tutorials: Website <https://www.odoo.com/slides/website-25>`_
    - `Odoo Tutorials: eCommerce <https://www.odoo.com/slides/ecommerce-26>`_

content/applications/websites/ecommerce/publish.rst

@@ -7,7 +7,6 @@ Launch my website
 .. toctree::
    :titlesonly:
 
-   ../website/publish/domain_name
    ../website/publish/on-premise_geo-ip-installation
    ../website/publish/translate
 

content/applications/websites/website.rst

@@ -10,6 +10,12 @@ Website
 Discover the best **Open-Source Website Builder** and learn how to build beautiful websites that
 convert visitors into leads or revenues.
 
+.. important::
+   Odoo offers a :ref:`free custom domain name <domain-name/odoo-register>` to all Odoo Online 
+   databases for one year. Visitors can then access your website with an address such as
+   ``www.example.com`` rather than the default ``example.odoo.com``.
+
+
 .. seealso::
    - `Odoo Tutorials: Website <https://www.odoo.com/slides/website-25>`_
    - `Odoo Tutorials: eCommerce <https://www.odoo.com/slides/ecommerce-26>`_

content/applications/websites/website/publish.rst

@@ -7,9 +7,5 @@ Publish
 .. toctree::
    :titlesonly:
 
-   publish/domain_name
    publish/translate
    publish/multi_website
-
-
-

content/applications/websites/website/publish/domain_name.rst

@@ -1,121 +0,0 @@
-=============================
-How to use my own domain name
-=============================
-
-By default, your Odoo Online instance and website have a *.odoo.com* domain name,
-for both the URL and the emails.
-But you can change to a custom one (e.g. www.yourcompany.com).
-
-What is a good domain name
-==========================
-Your website address is as important to your branding as the name of your
-business or organization, so put some thought into changing it for a proper
-domain. Here are some tips:
-
-- Simple and obvious
-- Easy to remember and spell
-- The shorter the better
-- Avoid special characters
-- Aim for a .com and/or your country extension
-
-Read more: `How to Choose a Domain Name for Maximum SEO <https://www.searchenginejournal.com/choose-a-domain-name-maximum-seo/158951/>`__
-
-How to buy a domain name
-========================
-Buy your domain name at a popular registrar:
-
-- `GoDaddy <https://www.godaddy.com>`__
-- `Namecheap <https://www.namecheap.com>`__
-- `OVH <https://www.ovh.com>`__
-
-.. note:: Steps to buy a domain name are pretty much straight forward.
-   In case of issue, check out those easy tutorials:
-
-   - `GoDaddy <https://roadtoblogging.com/buy-domain-name-from-godaddy>`__
-   - `Namecheap <https://www.loudtips.com/buy-domain-name-hosting-namecheap//>`__
-
-   Feel free to buy an email server to have email addresses using your domain name.
-   However don't buy any extra service to create or host your website.
-   This is Odoo's job!
-
-.. _custom_domain:
-
-
-How to apply my domain name to my Odoo instance
-===============================================
-First let's authorize the redirection (yourcompany.com -> yourcompany.odoo.com):
-
-* Open your Odoo.com account from your homepage.
-
-.. image:: media/domain_name01.png
-    :align: center
-
-* Go to the *Manage Databases* page.
-
-.. image:: media/domain_name02.png
-    :align: center
-
-* Click on *Domains* to the right of the database you would like to redirect.
-
-.. image:: media/domain_name03.png
-    :align: center
-
-* A database domain prompt will appear. Enter your custom domain
-  (e.g. www.yourcompany.com).
-
-
-.. image:: media/domain_name04.png
-    :align: center
-
-We can now apply the redirection from your domain name's manager account:
-
-* Log in to your account and search for the DNS Zones management page.
-
-* Create a CNAME record *www.yourdomain.com* pointing to *mywebsite.odoo.com*.
-  If you want to use the naked domain (e.g. yourdomain.com), you need to redirect
-  *yourdomain.com* to *www.yourdomain.com*.
-
-.. note:: Here are some specific guidelines to create a CNAME record:
-
-   - `GoDaddy <https://www.godaddy.com/help/add-a-cname-record-19236>`__
-   - `Namecheap <https://www.namecheap.com/support/knowledgebase/article.aspx/9646/10/how-can-i-set-up-a-cname-record-for-my-domain>`__
-   - `OVH <https://www.ovh.co.uk/g1519.exchange_20132016_how_to_add_a_cname_record>`__
-
-How to enable SSL (HTTPS) for my Odoo instance
-==============================================
-
-Until recently, Odoo users needed to use a third-party CDN service provider such as CloudFlare to enable SSL.
-
-It is not required anymore: Odoo generates the certificate for you automatically, using integration with `Let's Encrypt Certificate Authority and ACME protocol <https://letsencrypt.org/how-it-works/>`__.
-In order to get this, simply add your domain name in your customer portal (a separate certificate is generated for each domain name specified).
-
-.. warning::
-  **Please note that the certificate generation may take up to 24h.**
-
-If you already use CloudFlare or a similar service, you can keep using it or simply change for Odoo. The choice is yours.
-
-.. _app-website/web_base_url:
-
-How to make sure that all my URLs use my custom domain?
-=======================================================
-
-To set up the root URL of your website and of all the links sent in emails, you can ask an administrator of your database (any user in the *Settings* group) to perform a login from the login screen. It's as simple as that!
-
-If you want to do it manually, go to :menuselection:`Settings --> Technical --> System Parameters`.
-Find the entry called ``web.base.url`` (you can create it if it does not exist) and enter the full URL of your website, like ``https://www.myodoowebsite.com``.
-
-.. warning::
-  The URL must include the protocol (``https://`` or ``http://``) and must not end by a slash (``/``).
-
-If you want to block the root URL update when an administrator logs in, you can add a System Parameter called  ``web.base.url.freeze`` with its value set to  ``True``.
-
-
-My website is indexed twice by Google
-=====================================
-
-If you set up a custom domain *mydomain.com* name for *mydatabase.odoo.com*,
-Google indexes your website under both names. This is a limitation of the Odoo cloud platforms/
-
-.. seealso::
-
-  * :doc:`/applications/general/email_communication/email_servers`

content/applications/websites/website/publish/multi_website.rst

@@ -46,7 +46,7 @@ website. Follow the purple drops; they will help you in the first steps.
 
 .. note::
    If you run Odoo Online, don’t forget to redirect any new domain name to your Odoo database
-   (``CNAME``) and to authorize it Odoo-side. See :doc:`domain_name`.
+   (``CNAME``) and to authorize it Odoo-side. See :ref:`domain-name/existing`.
 
 Create the menu
 ===============
@@ -124,7 +124,7 @@ be redirected to the right website using GeoIP.
   See :doc:`on-premise_geo-ip-installation`
 
 .. seealso::
-   - :doc:`domain_name`
+   - :doc:`/administration/maintain/domain_names`
 
 Customize the visitor experience
 ================================

redirects.txt

@@ -247,6 +247,7 @@ administration/deployment/install.rst administration/install/install.rst
 administration/maintain/db_premise.rst administration/maintain/on_premise.rst                # db_premise -> on_premise
 administration/maintain/db_upgrade.rst administration/upgrade/process.rst                    # maintain/db_upgrade -> upgrade/process
 administration/odoo_sh/advanced/upgrade_your_database.rst administration/upgrade/odoo_sh.rst # odoo_sh/advanced/upgrade_your_database -> upgrade/odoo_sh
+applications/websites/website/publish/domain_name.rst administration/maintain/domain_names.rst  # applications/[...]/domain_name -> administration/maintain/domain_names
 
 developer/webservices/iap.rst                           developer/misc/api/iap.rst
 developer/webservices/odoo.rst                          developer/misc/api/odoo.rst