[MOV] documentation structure reorganization

This commit aims to improve the documentation's navigability by redefining some categories' purposes and titles. There is a redirection rule for each documentation page moved. This ensures that users won't have a 404 error message. task-3217827 closes odoo/documentation#8061 Signed-off-by: Jonathan Castillo (jcs) <jcs@odoo.com>
2024-03-04 12:02:08 +01:00
parent 41b3bd3bc9
commit 10cd2a061b
562 changed files with 644 additions and 643 deletions
@@ -7,9 +7,10 @@ Configuration
 .. toctree::
   :titlesonly:

+   configuration/domain_names
   configuration/address_autocomplete
   configuration/cookies_bar
   configuration/translate
   configuration/multi_website
-   configuration/unsplash
   configuration/spam_protection
+   configuration/cdn
@@ -0,0 +1,109 @@
+=======================================
+Set up a content delivery network (CDN)
+=======================================
+
+.. _reference/cdn/keycdn:
+
+Deploying with KeyCDN
+=====================
+
+A :abbr:`CDN (Content Delivery Network)` or *content distribution network*, is a geographically
+distributed network of servers that provides high speed internet content. The :abbr:`CDN (Content
+Delivery Network)` provides quick, high-quality content delivery for content-heavy websites.
+
+This document will guide you through the setup of a KeyCDN_ account with an Odoo powered website.
+
+Create a pull zone in the KeyCDN dashboard
+------------------------------------------
+
+On the KeyCDN dashboard, start by navigating to the :menuselection:`Zones` menu item on the left. On
+the form, give a value to the :guilabel:`Zone Name`, which will appear as part of the :abbr:`CDN
+(Content Delivery Network)`'s :abbr:`URL (Uniform Resource Locator)`. Then, set the :guilabel:`Zone
+Status` to :guilabel:`active` to engage the zone. For the :guilabel:`Zone Type` set the value to
+:guilabel:`Pull`, and then, finally, under the :guilabel:`Pull Settings`, enter the
+:guilabel:`Origin URL`— this address should be the full Odoo database :abbr:`URL (Uniform Resource
+Locator)`.
+
+.. example::
+   Use ``https://yourdatabase.odoo.com`` and replace the *yourdatabase* subdomain prefix with the
+   actual name of the database. A custom :abbr:`URL (Uniform Resource Locator)` can be used, as
+   well, in place of the Odoo subdomain that was provided to the database.
+
+.. image:: cdn/keycdn-zone.png
+   :align: center
+   :alt: KeyCDN's Zone configuration page.
+
+Under the :guilabel:`General Settings` heading below the zone form, click the :guilabel:`Show all
+settings` button to expand the zone options. This should be the last option on the page. After
+expanding the :guilabel:`General Settings` ensure that the :guilabel:`CORS` option is
+:guilabel:`enabled`.
+
+Next, scroll to the bottom of the zone configuration page and :guilabel:`Save` the changes. KeyCDN
+will indicate that the new zone will be deployed. This can take about 10 minutes.
+
+.. image:: cdn/zone-url.png
+   :align: center
+   :alt: KeyCDN deploying the new Zone.
+
+.. note::
+   A new :guilabel:`Zone URL` has been generated for your Zone, in this example it is
+   ``pulltest-xxxxx.kxcdn.com``. This value will differ for each database.
+
+Copy this :guilabel:`Zone URL` to a text editor for later, as it will be used in the next steps.
+
+Configure the Odoo instance with the new zone
+---------------------------------------------
+
+In the Odoo :guilabel:`Website` app, go to the :menuselection:`Settings` and then activate the
+:guilabel:`Content Delivery Network (CDN)` setting and copy/paste the :guilabel:`Zone URL` value
+from the earlier step into the :guilabel:`CDN Base URL` field. This field is only visible and
+configurable when the :ref:`developer mode <developer-mode>` is activated.
+
+.. note::
+   Ensure that there are two *forward slashes* (`//`) before the :guilabel:`CDN Base URL` and one
+   forward slash (`/`) after the :guilabel:`CDN Base URL`.
+
+:guilabel:`Save` the settings when complete.
+
+.. image:: cdn/cdn-base-url.png
+   :align: center
+   :alt: Activate the CDN setting in Odoo.
+
+Now the website is using the CDN for the resources matching the :guilabel:`CDN filters` regular
+expressions.
+
+In the HTML of the Odoo website, the :abbr:`CDN (content delivery network)` integration is evidenced
+as working properly by checking the :abbr:`URL (Uniform Resource Locators)` of images. The *CDN Base
+URL* value can be seen by using your web browser's :guilabel:`Inspect` feature on the Odoo website.
+Look for it's record by searching within the :guilabel:`Network` tab inside of devtools.
+
+.. image:: cdn/test-pull.png
+   :align: center
+   :alt: The CDN Base URL can be seen using the inspect function on the Odoo website.
+
+Prevent security issues by activating cross-origin resource sharing (CORS)
+--------------------------------------------------------------------------
+
+A security restriction in some browsers (such as Mozilla Firefox and Google Chrome) prevents a
+remotely linked CSS file to fetch relative resources on this same external server.
+
+If the :abbr:`CORS (Cross-Origin Resource Sharing)` option isn't enabled in the :guilabel:`CDN
+Zone`, the more obvious resulting problem on a standard Odoo website will be the lack of *Font
+Awesome* icons because the font file declared in the *Font Awesome* CSS won't be loaded from the
+remote server.
+
+When these cross-origin resource issues occur, a security error message similar to the output
+below will appear in the web browser's developer console:
+
+``Font from origin 'http://pulltest-xxxxx.kxcdn.com' has been blocked from loading /shop:1 by
+Cross-Origin Resource Sharing policy: No 'Access-Control-Allow-Origin' header is present on the
+requested resource. Origin 'http://yourdatabase.odoo.com' is therefore not allowed access.``
+
+.. image:: cdn/odoo-security-message.png
+   :align: center
+   :alt: Error message populated in the browser console.
+
+Enabling the :abbr:`CORS (Cross-Origin Resource Sharing)` option in the :abbr:`CDN (Content Delivery
+Network)` settings fixes this issue.
+
+.. _KeyCDN: https://www.keycdn.com
@@ -0,0 +1,314 @@
+============
+Domain names
+============
+
+Domain names are text-based addresses identifying online locations, such as websites. They provide a
+more memorable and recognizable way for people to navigate the internet than numerical IP addresses.
+
+**Odoo Online** and **Odoo.sh** databases use a **subdomain** of the `odoo.com` **domain** by
+default (e.g., `mycompany.odoo.com`).
+
+However, you can use a custom domain name instead by :ref:`registering a free domain name
+<domain-name/register>` (only available for Odoo Online databases) or by :ref:`configuring a
+domain name you already own <domain-name/existing>`.
+
+.. seealso::
+   `Odoo Tutorials: Register a free domain name [video]
+   <https://www.odoo.com/slides/slide/register-a-free-domain-name-1663>`_
+
+.. _domain-name/register:
+
+Register a free domain name with Odoo
+=====================================
+
+To register a one-year free domain name for your Odoo Online database, sign in to your account and
+go to the `database manager <https://www.odoo.com/my/databases>`_. Click the gear icon
+(:guilabel:`⚙️`) next to the database name and select :guilabel:`Domain Names`.
+
+.. image:: domain_names/domain-names.png
+   :alt: Accessing a database's domain names configuration
+
+Search for the desired domain name and check its availability.
+
+.. image:: domain_names/domain-search.png
+   :alt: Searching for an available domain name
+
+.. tip::
+   Ensure the Website app is installed if the domain name registration option does not appear.
+
+Select the desired domain name, fill in the :guilabel:`Domain Owner` form, and click
+:guilabel:`Register`. The chosen domain name is directly linked to the database, but you still need
+to :ref:`map your domain name to your Odoo website <domain-name/db-map>`.
+
+.. image:: domain_names/domain-owner.png
+   :alt: Filling in the domain owner information
+
+.. important::
+   A verification email from `noreply@domainnameverification.net` will be sent to the email address
+   provided in the :guilabel:`Domain Owner` form. It is essential to verify your email address to
+   keep the domain active and receive the renewal quote before expiration.
+
+The domain name registration is free for the first year. After this period, Odoo will continue to
+manage the domain in partnership with **Gandi.net**, the domain name registrar, and you will be
+charged `Gandi.net's renewal rate <https://www.gandi.net/en/domain>`_. Odoo sends a renewal
+quotation every year to the email address mentioned in the :guilabel:`Domain Owner` form several
+weeks before the expiration date of the domain. The domain is renewed automatically when the
+quotation is confirmed.
+
+.. note::
+   - The offer is only available for **Odoo Online** databases.
+   - The offer is limited to **one** domain name per client.
+   - The offer is limited to the registration of a **new** domain name.
+   - The offer is available to *One App Free* plans. Ensure that your website contains enough
+     original content for Odoo to verify that your request is legitimate and respects `Odoo's
+     Acceptable Use Policy <https://www.odoo.com/acceptable-use>`_. Given the high number of
+     requests, it can take Odoo several days to review them.
+
+.. _domain-name/register-dns:
+
+DNS records
+-----------
+
+To manage your free domain name :abbr:`DNS (domain name system)` records, open the `database manager
+<https://www.odoo.com/my/databases>`_, click the gear icon (:guilabel:`⚙️`) next to the database
+name, select :guilabel:`Domain Names`, and click :guilabel:`DNS`.
+
+- :guilabel:`A`: the A record holds the IP address of the domain. It is automatically created and
+  **cannot** be edited or deleted.
+- :guilabel:`CNAME`: CNAME records forward one domain or subdomain to another domain. One is
+  automatically created to map the `www.` subdomain to the database. If the database is renamed, the
+  CNAME record **must** also be renamed.
+- :guilabel:`MX`: MX records instruct servers on where to deliver emails.
+- :guilabel:`TXT`: TXT records can be used for different purposes (e.g., to verify domain name
+  ownership).
+
+Any modification to the DNS records can take up to **72 hours** to propagate worldwide on all
+servers.
+
+.. note::
+   `Submit a support ticket <https://www.odoo.com/help>`_ if you need assistance to manage your
+   domain name.
+
+Mailbox
+-------
+
+The one-year free domain name offer does **not** include a mailbox. There are two options to link
+your domain name with a mailbox.
+
+Use a subdomain
+~~~~~~~~~~~~~~~
+
+You can create a subdomain (e.g., `subdomain.yourdomain.com`) to use as an alias domain for the
+database. It allows users to create records in the database from emails received on their
+`email@subdomain.yourdomain.com` alias.
+
+To do so, open the `database manager <https://www.odoo.com/my/databases>`_, click the gear icon
+(:guilabel:`⚙️`) next to the database name, and go to :menuselection:`Domain Names --> DNS --> Add
+DNS record --> CNAME`. Next, enter the desired subdomain in the :guilabel:`Name` field (e.g.,
+`subdomain`), the original database domain with a period at the end (e.g., `mycompany.odoo.com.`) in
+the :guilabel:`Content` field, and click :guilabel:`Add record`.
+
+Then, add the alias domain as your *own domain* by clicking :guilabel:`Use my own domain`, entering
+the alias domain (e.g., `subdomain.yourdomain.com`), clicking :guilabel:`Verify`, and then
+:guilabel:`I confirm, it's done`.
+
+Finally, go to your database and open the :guilabel:`Settings`. Under the :guilabel:`Alias Domain`
+field, enter the alias domain (e.g., `subdomain.yourdomain.com`), click :guilabel:`Create`, and then
+:guilabel:`Save`.
+
+Use an external email provider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use an external email provider, you should configure an MX record. To do so, open the `database
+manager <https://www.odoo.com/my/databases>`_, click the gear icon (:guilabel:`⚙️`) next to the
+database name, click :menuselection:`Domain Names --> DNS --> Add DNS record --> MX`. The values you
+should enter for the :guilabel:`Name`, :guilabel:`Content`, and :guilabel:`Priority` fields depend
+on the external email provider.
+
+.. seealso::
+   - `Google Workspace: MX record values <https://support.google.com/a/answer/174125?hl=en>`_
+   - `Outlook and Exchange Online: Add an MX record for email <https://learn.microsoft.com/en-us/microsoft-365/admin/get-help-with-domains/create-dns-records-at-any-dns-hosting-provider?view=o365-worldwide#add-an-mx-record-for-email-outlook-exchange-online>`_
+
+.. _domain-name/existing:
+
+Configure an existing domain name
+=================================
+
+If you already have a domain name, you can use it for your Odoo website.
+
+.. warning::
+   It is strongly recommended to follow **in order** these three steps to avoid any :ref:`SSL
+   certificate validation <domain-name/ssl>` issues:
+
+   #. :ref:`Add a CNAME record <domain-name/cname>`
+   #. :ref:`Map your domain name to your Odoo database <domain-name/db-map>`
+   #. :ref:`Map your domain name to your Odoo website <domain-name/website-map>`
+
+.. _domain-name/cname:
+
+Add a CNAME record
+------------------
+
+Creating a CNAME record to forward your domain name to the address of your Odoo database is
+required.
+
+.. tabs::
+
+   .. group-tab:: Odoo Online
+
+      The CNAME record's target address should be your database's address as defined at its creation
+      (e.g., `mycompany.odoo.com`).
+
+   .. group-tab:: Odoo.sh
+
+      The CNAME record's target address can be the project's main address, which can be found on
+      Odoo.sh by going to :menuselection:`Settings --> Project Name`, or a specific branch
+      (production, staging or development) by going to :menuselection:`Branches --> select the
+      branch --> Settings --> Custom domains`, and clicking :guilabel:`How to set up my domain?`. A
+      message indicates which address your CNAME record should target.
+
+The specific instructions depend on your DNS hosting service.
+
+.. seealso::
+   - `GoDaddy: Add a CNAME record <https://www.godaddy.com/help/add-a-cname-record-19236>`_
+   - `Namecheap: How to create a CNAME record for your domain <https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain>`_
+   - `OVHcloud: Add a new DNS record <https://docs.ovh.com/us/en/domains/web_hosting_how_to_edit_my_dns_zone/#add-a-new-dns-record>`_
+   - `Cloudflare: Manage DNS records
+     <https://support.cloudflare.com/hc/en-us/articles/360019093151>`_
+
+Creating a CNAME record to map the `www` subdomain (`www.yourdomain.com`) as some visitors are used
+to typing `www.` before entering a domain name.
+
+.. example::
+   You own the domain name `yourdomain.com`, and your Odoo Online database's address is
+   `mycompany.odoo.com`. You want to access your Odoo database primarily with the domain
+   `www.yourdomain.com` but also with the naked domain :dfn:`(a domain name without any subdomains
+   or prefixes)` `yourdomain.com`.
+
+   To do so, create a CNAME record for the `www` subdomain, with `mycompany.odoo.com` as the
+   target. Next, create a redirect (301 permanent or visible redirect) to redirect visitors from
+   `yourdomain.com` to `wwww.yourdomain.com`.
+
+.. _domain-name/db-map:
+
+Map a domain name to an Odoo database
+-------------------------------------
+
+.. warning::
+   Ensure you have :ref:`added a CNAME record <domain-name/cname>` to your domain name's DNS
+   **before** mapping your domain name to your Odoo database.
+
+   Failing to do so may prevent the validation of the :ref:`SSL certificate <domain-name/ssl>` and
+   could result in a *certificate name mismatch* error. Web browsers often display this as a
+   warning, such as *"Your connection is not private"*.
+
+   If you encounter this error after mapping the domain name to your database, wait up to five
+   days, as the validation may still happen. If not, you can `submit a support ticket
+   <https://www.odoo.com/help>`_, including screenshots of your CNAME records.
+
+.. tabs::
+
+   .. group-tab:: Odoo Online
+
+      Open the `database manager <https://www.odoo.com/my/databases>`_, click the gear icon
+      (:guilabel:`⚙️`) next to the database name, and go to :menuselection:`Domain Names --> Use my
+      own domain`. Then, enter the domain name (e.g., `yourdomain.com`), click :guilabel:`Verify`
+      and :guilabel:`I confirm, it's done`.
+
+      .. image:: domain_names/map-database-online.png
+         :alt: Mapping a domain name to an Odoo Online database
+
+   .. group-tab:: Odoo.sh
+
+      On Odoo.sh, go to :menuselection:`Branches --> select your branch --> Settings --> Custom
+      domains`, type the domain name to add, then click :guilabel:`Add domain`.
+
+      .. image:: domain_names/map-database-sh.png
+         :alt: Mapping a domain name to an Odoo.sh branch
+
+      .. seealso::
+         :ref:`Odoo.sh branches: settings tab <odoosh-gettingstarted-branches-tabs-settings>`
+
+.. _domain-name/ssl:
+
+SSL encryption (HTTPS protocol)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**SSL encryption** allows visitors to navigate a website through a secure connection, which appears
+as the *https://* protocol at the beginning of a web address rather than the non-secure *http://*
+protocol.
+
+Odoo generates a separate SSL certificate for each domain :ref:`mapped to a database
+<domain-name/db-map>` using `Let's Encrypt's certificate authority and ACME protocol
+<https://letsencrypt.org/how-it-works/>`_.
+
+.. note::
+   - Certificate generation may take up to 24 hours.
+   - Several attempts to validate your certificate are made for five days after you map your domain
+     name to your database.
+   - If you use another service, you can keep using it or change to Odoo's.
+
+.. important::
+   No SSL certificate is generated for naked domains :dfn:`(domain names without any subdomains
+   or prefixes)`.
+
+.. _domain-name/web-base-url:
+
+Web base URL of a database
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+   If the Website app is installed on your database, skip this section and continue from the
+   :ref:`Map a domain name to a website <domain-name/website-map>` section.
+
+The *web base URL* or root URL of a database affects your main website address and all the
+links sent to your customers (e.g., quotations, portal links, etc.).
+
+To make your custom domain name the *web base URL* of your database, access your database using your
+custom domain name and log in as an administrator :dfn:`(a user part of the Settings access right
+group under Administration)`.
+
+.. warning::
+   If you access your database with the original Odoo address (e.g., `mycompany.odoo.com`), the *web
+   base URL* of your database will be updated accordingly. To prevent the automatic update of the
+   *web base URL* when an administrator logs in to the database, activate the :ref:`developer mode
+   <developer-mode>`, go to :menuselection:`Settings --> Technical --> System Parameters --> New`,
+   and enter `web.base.url.freeze` as the :guilabel:`Key` and `True` as the :guilabel:`Value`.
+
+.. note::
+   You can also set the web base URL manually. To do so, activate the :ref:`developer mode
+   <developer-mode>`, go to :menuselection:`Settings --> Technical --> System Parameters`, and
+   search for the `web.base.url` key (create it if necessary) and enter the full address of your
+   website as the value (e.g., `https://www.yourdomain.com`). The URL must include the protocol
+   `https://` (or `http://`) and *not* end with a slash (`/`).
+
+.. _domain-name/website-map:
+
+Map a domain name to an Odoo website
+------------------------------------
+
+Mapping your domain name to your website is different than mapping it to your database:
+
+- It defines your domain name as the main one for your website, helping search engines to index your
+  website correctly.
+- It defines your domain name as the base URL for your database, including portal links sent by
+  email to your customers.
+- If you have multiple websites, it maps your domain name to the appropriate website.
+
+Go to :menuselection:`Website --> Configuration --> Settings`. If you have multiple websites, select
+the one you want to configure. In the :guilabel:`Domain` field, enter the address of your website
+(e.g., `https://www.yourdomain.com`) and :guilabel:`Save`.
+
+.. warning::
+   Mapping your domain name to your Odoo website prevents Google Search from indexing your original
+   database address (e.g., `mycompany.odoo.com`).
+
+   If both addresses are already indexed, it may take some time before the indexation of the second
+   address is removed from Google Search. You can use the `Google Search Console
+   <https://search.google.com/search-console/welcome>`_ to fix the issue.
+
+.. note::
+   If you have multiple websites and companies on your database, make sure to select the right
+   :guilabel:`Company` under :menuselection:`Website --> Configuration --> 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.
@@ -9,7 +9,7 @@ help avoid confusion and make it easier to tailor your digital outreach strategi
 target audience.

 Each website can be designed and configured independently with its own :doc:`domain name
-</administration/maintain/domain_names>`, theme, pages,
+<domain_names>`, theme, pages,
 menus, :doc:`languages <translate>`, :doc:`products <../../ecommerce/managing_products/products>`,
 assigned sales team, etc. They can also :ref:`share content and pages
 <multi-website/website_content>`.
@@ -30,7 +30,7 @@ To create a new website, proceed as follows:
      :alt: New website button

 #. Specify the :guilabel:`Website Name` and :guilabel:`Website domain`. Each website must be
-   published under its own :doc:`domain </administration/maintain/domain_names>`.
+   published under its own :doc:`domain <domain_names>`.
 #. Adapt the :guilabel:`Company name`, :guilabel:`Languages` and :guilabel:`Default language`
   if needed.
 #. Click the :guilabel:`Create` button.
@@ -72,7 +72,7 @@ website.
 .. note::
   - Websites are created with the default settings; the settings are not copied from one website to
     the other.
-   - In a :doc:`multi-company environment <../../../general/users/companies>`, each website can be
+   - In a :doc:`multi-company environment </applications/general/companies>`, each website can be
     linked to a specific company in your database so that only company-related data (e.g.,
     products, jobs, events, etc.) is displayed on the website. To display company-specific data,
     set the desired company in the :guilabel:`Company` field.
@@ -1,30 +0,0 @@
-========
-Unsplash
-========
-
-**Unsplash** is a recognized stock photography library integrated with Odoo.
-
-If your database is hosted on **Odoo Online**, you can access Unsplash pictures without
-configuration.
-
-If your database is hosted on **Odoo.sh or on-premise**, proceed as follows:
-
-#. To **generate an Unsplash access key**, create or sign in to an `Unsplash account
-   <https://unsplash.com>`_.
-
-#. Access your `applications dashboard <https://unsplash.com/oauth/applications>`_, click
-   :guilabel:`New Application`, select all checkboxes, and click :guilabel:`Accept terms`.
-
-#. In the pop-up window, enter your :guilabel:`Application Name`, starting with the
-   prefix `Odoo:` (e.g., `Odoo: connection`), so Unsplash recognizes it as an Odoo instance. Then,
-   add a :guilabel:`Description` and click :guilabel:`Create application`.
-
-#. On the application details page, scroll down to the :guilabel:`Keys` section and copy the
-   :guilabel:`Access Key` and :guilabel:`Application ID`.
-
-#. In Odoo, go to :menuselection:`General Settings` and enable the :guilabel:`Unsplash Image
-   Library` feature. Then, enter the Unsplash :guilabel:`Access Key` and :guilabel:`Application ID`.
-
-.. warning::
-   As a non-Odoo Online user, you are limited to a test key with a maximum of 50 Unsplash requests
-   per hour.
@@ -140,7 +140,7 @@ URL redirects
 Redirecting URLs consists in sending visitors and search engines to a URL that is different from the
 one they originally requested. This technique is used, for example, to prevent broken links when you
 :ref:`delete a page <website/delete-page>`, :ref:`modify its URL <website/page_properties>`, or move
-your site to a new :doc:`domain </administration/maintain/domain_names>`. It can also be used to
+your site to a new :doc:`domain <configuration/domain_names>`. It can also be used to
 improve :doc:`pages/seo`.

 To access existing URL redirections and create new ones, :doc:`activate the developer mode