[REF] documentation: reorganize setup/install

Odoo setup/install documentation needed a re-organization and an update
to reflect the latest dependencies versions.
There was too much warnings and danger signs on this page.
Finally, the structure was not the same for each install method.

* As CentOs is actually too old to handle python3 dependencies for Odoo,
  rpm install method is explicitely mentioning Fedora 26.
* The "yum" package manager has been deprecated in Fedora and replaced
  with "dnf".
* As Debian and Ubuntu don't ship a python3-num2words package, the
  documentation must provide a hint on how to install the module using pip.
* The documentation was missing the virtualenv way of installing Odoo.
* Paragraphs mentioning configuration file were removed. The
  reference/cmdline page should be updated consequently.

1 files changed, 240 insertions, 198 deletions

diff --git a/doc/setup/install.rst b/doc/setup/install.rst
index 04730ab94bd..71a6ea7edb7 100644
--- a/doc/setup/install.rst
+++ b/doc/setup/install.rst
@@ -11,39 +11,21 @@ on the intended use case.
 
 This documents attempts to describe most of the installation options.
 
-:ref:`setup/install/demo`
-    The simplest "installation", only suitable for getting a quick feel for
-    Odoo or trying something out
-:ref:`setup/install/saas`
-    Trivial to start with and fully managed and migrated by Odoo S.A., can be
-    used to both test Odoo and use it for your business, prevents complex
-    customization (i.e. incompatible with custom modules or the Odoo Apps Store).
-
-    Can be used for both testing Odoo and long-term production use.
-:ref:`setup/install/packaged`
-    Simple to get started, allows more flexibility in hosting and deploying
-    the system and greater control over where data is stored. The maintenance
-    burden is shifted to the user.
+:ref:`setup/install/online`
+    The easiest way to use Odoo in production or to try it.
 
+:ref:`setup/install/packaged`
     Suitable for testing Odoo, developing modules and can be used for
     long-term production use with additional deployment and maintenance work.
+
 :ref:`setup/install/source`
-    Harder to get started than :ref:`setup/install/packaged`, provides
-    even greater flexibility: packaged installers don't generally allow
-    multiple running Odoo versions on the same system, and don't provide easy
-    source access to Odoo itself.
-
-    Good for developing modules, can be used as base for production
-    deployment.
-
-    The source code can be obtained by downloading a tarball or using git.
-    Using git is strongly advised, as it makes it easier to update, switch
-    between multiple versions (including the current development version)
-    or contribute.
-`docker image <https://registry.hub.docker.com/_/odoo/>`_
+    Provides greater flexibility:  e.g. allow multiple running Odoo versions on
+    the same system. Good for developing modules, can be used as base for
+    production deployment.
+
+:ref:`setup/install/docker`
     If you usually use docker_ for development or deployment, an official
-    docker_ base image is available, see the image's help document for more
-    information.
+    docker_ base image is available.
 
 .. _setup/install/editions:
 
@@ -58,23 +40,13 @@ available to anyone.
 If you already use the Community version and wish to upgrade to Enterprise, please
 refer to :ref:`setup/enterprise` (except for :ref:`setup/install/source`).
 
-If you wish to access the Enterprise installers/source code, you can:
-
-* Go to the Download_ page and log in with your customer credentials
-* Download the source on GitHub using git_(available to partners only)
+.. _setup/install/online:
 
-.. note:: If you do not have access to our Enterprise repository, you can request
-    it be e-mailing your sales representative or our online support with
-    your subscription number and GitHub username. (available to partners only)
-
-.. warning:: Enterprise deb and rpm packages do not have repositories, so automatic
-    update will not work. Reinstalling the latest package version will be needed
-    to update manually an installation.
-
-.. _setup/install/demo:
+Online
+======
 
 Demo
-====
+----
 
 To simply get a quick idea of Odoo, demo_ instances are available. They are
 shared instances which only live for a few hours, and can be used to browse
@@ -82,14 +54,15 @@ around and try things out with no commitment.
 
 Demo_ instances require no local installation, just a web browser.
 
-.. _setup/install/saas:
-
 SaaS
-====
+----
 
-Odoo's SaaS_ provides private instances and starts out free. It can be used to
-discover and test Odoo and do non-code customizations without having to
-install it locally.
+Trivial to start with, fully managed and migrated by Odoo S.A., Odoo's SaaS_
+provides private instances and starts out free. It can be used to discover and
+test Odoo and do non-code customizations (i.e. incompatible with custom modules
+or the Odoo Apps Store) without having to install it locally.
+
+Can be used for both testing Odoo and long-term production use.
 
 Like demo_ instances, SaaS_ instances require no local installation, a web
 browser is sufficient.
@@ -127,26 +100,39 @@ Windows
 
 Odoo will automatically be started at the end of the installation.
 
-Configuration
+Linux
+-----
+
+Debian/Ubuntu
 '''''''''''''
 
-The :ref:`configuration file <reference/cmdline/config>` can be found at
-:file:`{%PROGRAMFILES%}\\Odoo 11.0-{id}\\server\\odoo.conf`.
+Odoo 11.0 'deb' package currently supports `Debian Stretch`_, `Ubuntu Xenial`_,
+`Ubuntu Zesty`_ and `Ubuntu Artful`_.
 
-The configuration file can be edited to connect to a remote Postgresql, edit
-file locations or set a dbfilter.
+Prepare
+^^^^^^^
 
-To reload the configuration file, restart the Odoo service via
-:menuselection:`Services --> odoo server`.
+Odoo needs a `PostgreSQL`_ server to run properly. The default configuration for
+the Odoo 'deb' package is to use the PostgreSQL server on the same host as your
+Odoo instance. Execute the following command as root in order to install
+PostgreSQL server :
 
-Deb
----
+.. code-block:: console
+
+  # apt-get install postgresql -y
+
+In order to print PDF reports, you must install wkhtmltopdf_ yourself:
+the version of wkhtmltopdf_ available in debian repositories does not support
+headers and footers so it can not be installed automatically.
+The recommended version is 0.12.1 and is available on `the wkhtmltopdf download page`_,
+in the archive section.
 
-Community
-'''''''''
+Repository
+^^^^^^^^^^
 
-To install Odoo 11.0 Community on Debian-based distribution, execute the following
-commands as root:
+Odoo S.A. provides a repository that can be used with  Debian and Ubuntu
+distributions. It can be used to install Odoo Community Edition by executing the
+following commands as root:
 
 .. code-block:: console
 
@@ -156,26 +142,33 @@ commands as root:
 
 You can then use the usual ``apt-get upgrade`` command to keep your installation up-to-date.
 
-Enterprise
-''''''''''
+At this moment, there is no repository for the Enterprise Edition.
+
+Deb Package
+^^^^^^^^^^^
+
+Instead of using the repository as described above, the 'deb' package can be
+downloaded here:
 
-For Odoo 11.0 Enterprise, get the package from the Download_ page. You can then
-use ``gdebi``:
+* Community Edition: `nightly`_
+* Enterprise Edition `Download`_
+
+You can then use ``gdebi``:
 
 .. code-block:: console
 
-    # apt-get install postgresql -y
     # gdebi <path_to_installation_package>
 
 Or ``dpkg`` (handles less dependencies automatically):
 
 .. code-block:: console
 
-    # apt-get install postgresql -y
     # dpkg -i <path_to_installation_package> # this probably fails with missing dependencies
     # apt-get install -f # should install the missing dependencies
     # dpkg -i <path_to_installation_package>
 
+This will install Odoo as a service, create the necessary PostgreSQL_ user
+and automatically start the server.
 
 .. warning:: The 3 following python packages are only suggested by the Debian package.
              Those packages are not available in Ubuntu Xenial (16.04).
@@ -193,102 +186,72 @@ One way to do it, is simply using pip3 like this:
     $ sudo apt install libldap2-dev libsasl2-dev
     $ sudo pip3 install pyldap
 
-This will install Odoo as a service, create the necessary PostgreSQL_ user
-and automatically start the server.
-
-.. danger:: to print PDF reports, you must install wkhtmltopdf_ yourself:
-            the version of wkhtmltopdf_ available in debian repositories does
-            not support headers and footers so it can not be installed
-            automatically. The recommended version is 0.12.1 and is available on
-            `the wkhtmltopdf download page`_, in the archive section. As there
-            is no official release for Debian Jessie, you can find ours on the
-            extra_ section of our nightly server.
-
-Configuration
-'''''''''''''
-
-The :ref:`configuration file <reference/cmdline/config>` can be found at
-:file:`/etc/odoo/odoo.conf`
+.. warning:: Debian 9 and Ubuntu do not provide a package for the python module
+             num2words.
+             Textual amounts will not be rendered by Odoo and this could cause
+             problems with the "l10n_mx_edi" module.
 
-When the configuration file is edited, Odoo must be restarted using
-``service``:
+If you need this feature, you can install the python module like this:
 
 .. code-block:: console
 
-    $ sudo service odoo restart
-    Restarting odoo: ok
+    $ sudo pip3 install num2words
 
-RPM
----
+Fedora
+''''''
 
-.. warning::
-
-    As of 2017, Fedora 26 is recommended. CentOS does not have the minimum
-    Python requirements (3.5) for Odoo 11.0.
-
-.. warning::
-
-    with RHEL-based distributions (RHEL, CentOS, Scientific Linux), EPEL_ must
-    be added to the distribution's repositories for all of Odoo's
-    dependencies to be available. For CentOS:
-
-    .. code-block:: console
+Odoo 11.0 'rpm' package supports Fedora 26.
+As of 2017, CentOS does not have the minimum Python requirements (3.5) for
+Odoo 11.0.
 
-        $ sudo yum install -y epel-release
-
-    For other RHEL-based distribution, see the EPEL_ documentation.
-
-Community
-'''''''''
-
-Execute the following commands to install Odoo 11.0 Community on your server:
+Prepare
+^^^^^^^
+Odoo needs a `PostgreSQL`_ server to run properly. Assuming that the 'sudo'
+command is available and configured properly, run the following commands :
 
 .. code-block:: console
 
-    $ sudo yum install -y postgresql-server
-    $ sudo postgresql-setup initdb
+    $ sudo dnf install -y postgresql-server
+    $ sudo postgresql-setup --initdb --unit postgresql
     $ sudo systemctl enable postgresql
     $ sudo systemctl start postgresql
-    $ sudo yum install yum-utils
-    $ sudo yum-config-manager --add-repo=https://nightly.odoo.com/11.0/nightly/rpm/odoo.repo
-    $ sudo yum install -y odoo
-    $ sudo systemctl enable odoo
-    $ sudo systemctl start odoo
 
-Enterprise
-''''''''''
+In order to print PDF reports, you must install wkhtmltopdf_ yourself:
+the version of wkhtmltopdf_ available in debian repositories does not support
+headers and footers so it can not be installed automatically.
+The recommended version is 0.12.1 and is available on `the wkhtmltopdf download page`_,
+in the archive section.
 
-For Odoo 11.0 Enterprise, get the package from the Download_ page. Then run:
+Repository
+^^^^^^^^^^
+
+Odoo S.A. provides a repository that can be used with the Fedora distibutions.
+It can be used to install Odoo Community Edition by executing the following
+commands:
 
 .. code-block:: console
 
-    $ sudo yum install -y postgresql-server
-    $ sudo postgresql-setup initdb
-    $ sudo systemctl enable postgresql
-    $ sudo systemctl start postgresql
-    $ sudo yum localinstall odoo_11.0.latest.noarch.rpm
+    $ sudo dnf config-manager --add-repo=https://nightly.odoo.com/11.0/nightly/rpm/odoo.repo
+    $ sudo dnf install -y odoo
     $ sudo systemctl enable odoo
     $ sudo systemctl start odoo
 
+RPM package
+^^^^^^^^^^^
 
-.. danger:: to print PDF reports, you must install wkhtmltopdf_ yourself:
-            the version of wkhtmltopdf_ available in Fedora/CentOS
-            repositories does not support headers and footers so it can not
-            be installed automatically. Use the version available on
-            `the wkhtmltopdf download page`_.
-
-Configuration
-'''''''''''''
+Instead of using the repository as described above, the 'rpm' package can be
+downloaded here:
 
-The :ref:`configuration file <reference/cmdline/config>` can be found at
-:file:`/etc/odoo/odoo.conf`
+* Community Edition: `nightly`_
+* Enterprise Edition `Download`_
 
-When the configuration file is edited, Odoo must be restarted via SystemD:
+Once downloaded, the package can be installed using the 'dnf' package manager:
 
 .. code-block:: console
 
-    $ sudo systemctl restart odoo
-
+    $ sudo dnf localinstall odoo_11.0.latest.noarch.rpm
+    $ sudo systemctl enable odoo
+    $ sudo systemctl start odoo
 
 .. _setup/install/source:
 
@@ -310,65 +273,8 @@ edit a configuration file.
 Finally it provides greater control over the system's set up, and allows more
 easily keeping (and running) multiple versions of Odoo side-by-side.
 
-Community
----------
-
-There are two way to get the odoo source source zip or git.
-
-* Odoo zip can be downloaded from  our nightly_ server or our Download_  page,
-  the zip file then needs to be uncompressed to use its content
-
-* git allows simpler update and easier switching between different versions
-  of Odoo. It also simplifies maintaining non-module patches and
-  contributions.  The primary drawback of git is that it is significantly
-  larger than a tarball as it contains the entire history of the Odoo project.
-
-  The git repository is https://github.com/odoo/odoo.git for the Community
-  version.
-
-  Downloading it requires a `git client <http://git-scm.com/download/>`_
-  (which may be available via your distribution on linux) and can be performed
-  using the following command:
-
-  .. code-block:: console
-
-      $ git clone https://github.com/odoo/odoo.git
-
-Enterprise
-----------
-
-If you have access to the Enterprise repository (see :ref:`setup/install/editions`
-if you wish to get access), you can use this command to fetch the addons:
-
-.. code-block:: console
-
-  $ git clone https://github.com/odoo/enterprise.git
-
-If you use git_, you must modify the :option:`--addons-path <odoo-bin --addons-path>`
-parameter of your launch command (``init.d``, custom script, configuration file,
-etc.). The Enterprise addons folder should be included **before** the default
-addons folder.
-
-For example:
-
-.. code-block:: console
-
-  $ odoo-bin --addons-path=~/src/custom_modules,~/src/enterprise,~/src/odoo/addons
-
-.. warning:: The Enterprise git repository **does not contain the full Odoo
-    source code**. It is only a collection of extra add-ons. The main server
-    code is in the Community version.  Running the Enterprise version actually
-    means running the server from the Community version with the addons-path option
-    set to the folder with the Enterprise version.
-    
-    You need to clone both the Community and Enterprise repository to have a working
-    Odoo installation. The Download_ page contains the entire source code but is not
-    updateable as easily.
-
-
-
-Installing dependencies
------------------------
+Prepare
+-------
 
 Source installation requires manually installing dependencies:
 
@@ -514,12 +420,58 @@ Source installation requires manually installing dependencies:
 
         C:\> npm install -g less
 
+Fetch the sources
+-----------------
+
+There are two ways to obtain the Odoo source code: zip or git.
+
+* Odoo zip can be downloaded from  our nightly_ server or our Download_  page,
+  the zip file then needs to be uncompressed to use its content
+
+* git allows simpler update and easier switching between different versions
+  of Odoo. It also simplifies maintaining non-module patches and
+  contributions.  The primary drawback of git is that it is significantly
+  larger than a tarball as it contains the entire history of the Odoo project.
+
+Community Edition
+'''''''''''''''''
+
+The git repository is https://github.com/odoo/odoo.git for the Community
+edition.
+
+Downloading it requires a `git client <http://git-scm.com/download/>`_
+(which may be available via your distribution on linux) and can be performed
+using the following command:
+
+.. code-block:: console
+
+    $ git clone https://github.com/odoo/odoo.git
+
+Enterprise Edition
+''''''''''''''''''
+
+If you have access to the Enterprise repository (see :ref:`setup/install/editions`
+if you wish to get access), you can use this command to fetch the addons:
+
+.. code-block:: console
+
+  $ git clone https://github.com/odoo/enterprise.git
+
+.. note:: The Enterprise git repository **does not contain the full Odoo
+    source code**. It is only a collection of extra add-ons. The main server
+    code is in the Community version.  Running the Enterprise version actually
+    means running the server from the Community version with the addons-path option
+    set to the folder with the Enterprise version.
+
+    You need to clone both the Community and Enterprise repository to have a working
+    Odoo installation
+
 Running Odoo
 ------------
 
 Once all dependencies are set up, Odoo can be launched by running ``odoo-bin``.
 
-.. warning:: For the Enterprise edition, you must specify the :file:`enterprise`
+.. tip:: For the Enterprise edition, you must specify the :file:`enterprise`
     addons folder when starting your server. You can do so by providing the path
     to your :file:`enterprise` folder in the ``addons-path`` parameter. Please
     note that the :file:`enterprise` folder must come before the default
@@ -560,9 +512,98 @@ Under Unix a typical way to execute odoo would be:
 Where ``../mymodules`` is a directory with additional addons and ``mydb`` the
 default db to serve on localhost:8069
 
+Virtualenv
+----------
+
+Virtualenv_ is a tool to create Python isolated environments because it's
+sometimes preferable to not mix your distribution python modules packages
+with globally installed python modules with pip.
+
+This section will explain how to run Odoo in a such isolated Python environment.
+
+Here we are going to use virtualenvwrapper_ which is a set of shell scripts that
+makes the use of virtualenv easier.
+
+The examples below are based on a Debian 9 distribution but could be adapted on
+any platform where virtualenvwrapper_ and virtualenv_ are able to run.
+
+This section assumes that you obtained the Odoo sources from the zip file or the
+git repository as explained above. The same apply for postgresql installation
+and configuration.
+
+Install virtualenvwrapper
+'''''''''''''''''''''''''
+
+.. code-block:: console
+
+  $ sudo apt install virtualenvwrapper
+  $ source /usr/share/virtualenvwrapper/virtualenvwrapper.sh
+
+This will install virtualenvwrapper_ and activate it immediately.
+Now, let's install the tools required to build Odoo dependencies if needed:
+
+.. code-block:: console
+
+  $ sudo apt install build-essential python3-dev libxslt-dev libzip-dev libldap2-dev libsasl2-dev
+
+Create an isolated environment
+''''''''''''''''''''''''''''''
+
+Now we can create a virtual environment for Odoo like this:
+
+.. code-block:: console
+
+  $ mkvirtualenv -p /usr/bin/python3 odoo-venv
+
+With this command, we ask for an isolated Python3 environment that will be named
+"odoo-env". If the command works as expected, your shell is now using this
+environment. Your prompt should have changed to remind you that you are using
+an isolated environment. You can verify with this command:
+
+.. code-block:: console
+
+  $ which python3
+
+This command should show you the path to the Python interpreter located in the
+isolated environment directory.
+
+Now let's install the Odoo required python packages:
+
+.. code-block:: console
+
+  $ cd your_odoo_sources_path
+  $ pip install -r requirements.txt
+
+After a little while, you should be ready to run odoo from the command line as
+explained above.
+
+When you you want to leave the virtual environment, just issue this command:
+
+.. code-block:: console
+
+  $ deactivate
+
+Whenever you want to work again with your 'odoo-venv' environment:
+
+.. code-block:: console
+
+  $ workon odoo-venv
+
+.. _setup/install/docker:
+
+Docker
+======
+
+The full documentation on how to use Odoo with Docker can be found on the
+offcial Odoo `docker image <https://registry.hub.docker.com/_/odoo/>`_ page.
+
 .. _demo: https://demo.odoo.com
 .. _docker: https://www.docker.com
 .. _Download: https://www.odoo.com/page/download
+.. _Debian Stretch: https://www.debian.org/releases/stretch/
+.. _Ubuntu Xenial: http://releases.ubuntu.com/16.04/
+.. _Ubuntu Zesty: http://releases.ubuntu.com/17.04/
+.. _Ubuntu Artful: http://releases.ubuntu.com/17.10/
 .. _EPEL: https://fedoraproject.org/wiki/EPEL
 .. _PostgreSQL: http://www.postgresql.org
 .. _the official installer:
@@ -579,7 +620,8 @@ default db to serve on localhost:8069
 .. _macports: https://www.macports.org
 .. _homebrew: http://brew.sh
 .. _wheels: https://wheel.readthedocs.org/en/latest/
-.. _virtual environment: http://docs.python-guide.org/en/latest/dev/virtualenvs/
+.. _virtualenv: https://pypi.python.org/pypi/virtualenv
+.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/
 .. _pywin32: http://sourceforge.net/projects/pywin32/files/pywin32/
 .. _the repository: https://github.com/odoo/odoo
 .. _git: http://git-scm.com