[IMP] doc: rewrite of the source install page

Prior to this commit, the documentation page for the installation of Odoo had lots of inconsistencies, errouneous information and a bad structure.

This commit restructures the page to split the Source Install chapter into three sections for Windows, Linux and Mac OS.
Each section is entirely rewritten to be accurate, logical, clean, easy to understand and focused on its purpose (removed tutorials of non-Odoo softwares).

task-2072822

closes odoo/odoo#37001

Signed-off-by: Victor Feyens (vfe) <vfe@odoo.com>

2 files changed, 406 insertions, 251 deletions

diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst
index ddbe50a2b33..e954a5922df 100644
--- a/doc/reference/cmdline.rst
+++ b/doc/reference/cmdline.rst
@@ -442,56 +442,6 @@ Multiprocessing
 
     For multi-processing mode, this is in addition to the HTTP worker processes.
 
-.. _reference/cmdline/scaffold:
-
-Scaffolding
-===========
-
-.. program:: odoo-bin scaffold
-
-Scaffolding is the automated creation of a skeleton structure to simplify
-bootstrapping (of new modules, in the case of Odoo). While not necessary it
-avoids the tedium of setting up basic structures and looking up what all
-starting requirements are.
-
-Scaffolding is available via the :command:`odoo-bin scaffold` subcommand.
-
-.. option:: name (required)
-
-    the name of the module to create, may munged in various manners to
-    generate programmatic names (e.g. module directory name, model names, …)
-
-.. option:: destination (default=current directory)
-
-    directory in which to create the new module, defaults to the current
-    directory
-
-.. option:: -t <template>
-
-    a template directory, files are passed through jinja2_ then copied to
-    the ``destination`` directory
-
-.. code-block:: console
-
-    $ odoo_bin scaffold my_module /addons/
-
-This will create module *my_module* in directory */addons/*.
-
-Shell
-=====
-
-Odoo command-line also allows to launch odoo as a python console environment.
-This enables direct interaction with the :ref:`orm <reference/orm>` and its functionalities.
-
-
-.. code-block:: console
-
-   $ odoo_bin shell
-
-.. option:: --shell-interface (ipython|ptpython|bpython|python)
-
-    Specify a preferred REPL to use in shell mode.
-
 .. _reference/cmdline/config:
 
 Configuration file
@@ -534,3 +484,55 @@ to that file.
 .. _Werkzeug's proxy support:
     http://werkzeug.pocoo.org/docs/contrib/fixers/#werkzeug.contrib.fixers.ProxyFix
 .. _pyinotify: https://github.com/seb-m/pyinotify/wiki
+
+
+Shell
+=====
+
+Odoo command-line also allows to launch odoo as a python console environment.
+This enables direct interaction with the :ref:`orm <reference/orm>` and its functionalities.
+
+
+.. code-block:: console
+
+   $ odoo_bin shell
+
+.. option:: --shell-interface (ipython|ptpython|bpython|python)
+
+    Specify a preferred REPL to use in shell mode.
+
+
+.. _reference/cmdline/scaffold:
+
+Scaffolding
+===========
+
+.. program:: odoo-bin scaffold
+
+Scaffolding is the automated creation of a skeleton structure to simplify
+bootstrapping (of new modules, in the case of Odoo). While not necessary it
+avoids the tedium of setting up basic structures and looking up what all
+starting requirements are.
+
+Scaffolding is available via the :command:`odoo-bin scaffold` subcommand.
+
+.. option:: name (required)
+
+    the name of the module to create, may munged in various manners to
+    generate programmatic names (e.g. module directory name, model names, …)
+
+.. option:: destination (default=current directory)
+
+    directory in which to create the new module, defaults to the current
+    directory
+
+.. option:: -t <template>
+
+    a template directory, files are passed through jinja2_ then copied to
+    the ``destination`` directory
+
+.. code-block:: console
+
+    $ odoo_bin scaffold my_module /addons/
+
+This will create module *my_module* in directory */addons/*.
\ No newline at end of file
diff --git a/doc/setup/install.rst b/doc/setup/install.rst
index 7393292eb46..d42becb4f90 100644
--- a/doc/setup/install.rst
+++ b/doc/setup/install.rst
@@ -1,5 +1,6 @@
 :banner: banners/installing_odoo.jpg
 
+
 .. _setup/install:
 
 ===============
@@ -27,6 +28,7 @@ This documents attempts to describe most of the installation options.
     If you usually use docker_ for development or deployment, an official
     docker_ base image is available.
 
+
 .. _setup/install/editions:
 
 Editions
@@ -40,6 +42,7 @@ 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`).
 
+
 .. _setup/install/online:
 
 Online
@@ -67,6 +70,7 @@ 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.
 
+
 .. _setup/install/packaged:
 
 Packaged installers
@@ -81,14 +85,14 @@ but may be difficult to keep up-to-date.
 
 Official Community packages with all relevant dependency requirements are
 available on our nightly_ server. Both Communtiy and Enterprise packages can
-be downloaded from our Download_ page (you must to be logged in as a paying
+be downloaded from our download_ page (you must to be logged in as a paying
 customer or partner to download the Enterprise packages).
 
 Windows
 -------
 
 * Download the installer from our nightly_ server (Community only)
-  or the Windows installer from the Download_ page (any edition)
+  or the Windows installer from the download_ page (any edition)
 * Run the downloaded file
 
   .. warning:: on Windows 8, you may see a warning titled "Windows protected
@@ -252,325 +256,475 @@ Once downloaded, the package can be installed using the 'dnf' package manager:
     $ sudo systemctl enable odoo
     $ sudo systemctl start odoo
 
+
 .. _setup/install/source:
 
 Source Install
 ==============
 
-The source "installation" really is about not installing Odoo, and running
-it directly from source instead.
+The source "installation" is really about not installing Odoo, and running it directly from source
+instead.
 
-This can be more convenient for module developers as the Odoo source is
-more easily accessible than using packaged installation (for information or
-to build this documentation and have it available offline).
+This can be more convenient for module developers as the Odoo source is more easily accessible
+than using packaged installation (for information or to build this documentation and have it
+available offline).
 
-It also makes starting and stopping Odoo more flexible and explicit than the
-services set up by the packaged installations, and allows overriding settings
-using :ref:`command-line parameters <reference/cmdline>` without needing to
-edit a configuration file.
+It also makes starting and stopping Odoo more flexible and explicit than the services set up by the
+packaged installations, and allows overriding settings using
+:ref:`command-line parameters <reference/cmdline>` without needing to 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.
+Finally it provides greater control over the system's set up, and allows to more easily keep
+(and run) multiple versions of Odoo side-by-side.
 
-Prepare
+Windows
 -------
 
-Source installation requires manually installing dependencies:
+Fetch the sources
+'''''''''''''''''
+
+There are two ways to obtain the source code of Odoo: as a zip **archive** or through **git**.
+
+Archive
+^^^^^^^
+
+Community Edition:
 
-* Python 3.5+.
+* `Official download page <download_>`_
+* `GitHub repository <community-repository_>`_
+* `Nightly server <nightly_>`_
 
-  - on Linux and OS X, using your package manager if not installed by default
+Enterprise Edition:
 
-    .. note:: on some system, ``python`` command refers to Python 2 (outdated)
-              or to Python 3 (supported). Make sure you are using the right
-              version and that the alias ``python3`` is present in your
-              :envvar:`PATH`
+* `Official download page <download_>`_
+* `GitHub repository <enterprise-repository_>`_
 
-  - on Windows, use `the official Python 3 installer
-    <https://www.python.org/downloads/windows/>`_.
+Git
+^^^
 
-    .. warning:: select "add python.exe to Path" during installation, and
-                 reboot afterwards to ensure the :envvar:`PATH` is updated
+The following requires git_ to be installed on your machine and that you have basic knowledge of
+git commands.
 
-    .. note:: if Python is already installed, make sure it is 3.5 or above,
-              previous versions are not compatible with Odoo.
+Community Edition:
 
-* PostgreSQL, to use a local database
+.. code-block:: doscon
 
-  After installation you will need to create a postgres user: by default the
-  only user is ``postgres``, and Odoo forbids connecting as ``postgres``.
+    C:\> git clone https://github.com/odoo/odoo.git
 
-  - on Linux, use your distribution's package, then create a postgres user
-    named like your login:
 
-    .. code-block:: console
+Enterprise Edition: (see :ref:`setup/install/editions` to get access)
 
-        $ sudo su - postgres -c "createuser -s $USER"
+.. code-block:: doscon
 
-    Because the role login is the same as your unix login unix sockets can be
-    use without a password.
+  C:\> git clone https://github.com/odoo/enterprise.git
 
-  - on OS X, `postgres.app <http://postgresapp.com>`_ is the simplest way to
-    get started, then create a postgres user as on Linux
+.. 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 Enterprise
+          installation.
 
-  - on Windows, use `PostgreSQL for windows`_ then
+Prepare
+'''''''
 
-    - add PostgreSQL's ``bin`` directory (default:
-      ``C:\Program Files\PostgreSQL\9.4\bin``) to your :envvar:`PATH`
-    - create a postgres user with a password using the pg admin gui: open
-      pgAdminIII, double-click the server to create a connection, select
-      :menuselection:`Edit --> New Object --> New Login Role`, enter the
-      usename in the :guilabel:`Role Name` field (e.g. ``odoo``), then open
-      the :guilabel:`Definition` tab and enter the password (e.g. ``odoo``),
-      then click :guilabel:`OK`.
+Python
+^^^^^^
 
-      The user and password must be passed to Odoo using either the
-      :option:`-w <odoo-bin -w>` and :option:`-r <odoo-bin -r>` options or
-      :ref:`the configuration file <reference/cmdline/config>`
+Odoo requires Python 3.5 or later to run. Use the the official `Python 3 installer
+<https://www.python.org/downloads/windows/>`_ to download and install Python 3 on your machine.
 
-* Python dependencies listed in the :file:`requirements.txt` file.
+During installation, check **Add Python 3 to PATH**, then click **Customize Installation** and make
+sure that **pip** is checked.
 
-  - on Linux, python dependencies may be installable with the system's package
-    manager or using pip.
+.. note:: If Python 3 is already installed, make sure that it is 3.5 or above, as previous versions
+          are not compatible with Odoo.
 
-    For libraries using native code (Pillow, lxml, greenlet, gevent, psycopg2,
-    ldap) it may be necessary to install development tools and native
-    dependencies before pip is able to install the dependencies themselves.
-    These are available in ``-dev`` or ``-devel`` packages for Python,
-    Postgres, libxml2, libxslt, libevent, libsasl2 and libldap2. Then the Python
-    dependecies can themselves be installed:
+          .. code-block:: doscon
 
-    .. code-block:: console
+              C:\> python3 --version
 
-        $ pip3 install -r requirements.txt
+          Verify also that pip_ is installed for this version.
 
-  - on OS X, you will need to install the Command Line Tools
-    (``xcode-select --install``) then download and install a package manager
-    of your choice (homebrew_, macports_) to install non-Python dependencies.
-    pip can then be used to install the Python dependencies as on Linux:
+          .. code-block:: doscon
 
-    .. code-block:: console
+              C:\> pip3 --version
 
-        $ pip3 install -r requirements.txt
+PostgreSQL
+^^^^^^^^^^
 
-  - on Windows you need to install some of the dependencies manually, tweak the
-    requirements.txt file, then run pip to install the remaning ones.
+Odoo uses PostgreSQL as database management system. Download and install the `latest version of
+PostgreSQL <https://www.postgresql.org/download/windows/>`_.
 
-    Install ``psycopg`` using the installer here
-    http://www.stickpeople.com/projects/python/win-psycopg/
+By default, the only user is `postgres` but Odoo forbids connecting as `postgres`, so you need to
+create a new PostgreSQL user:
 
-    Then use pip to install the dependencies using the following
-    command from a cmd.exe prompt (replace ``\YourOdooPath`` by the actual
-    path where you downloaded Odoo):
+#. Add PostgreSQL's `bin` directory (by default: `C:\\Program Files\\PostgreSQL\\<version>\\bin`) to
+   your `PATH`.
+#. Create a postgres user with a password using the pg admin gui:
 
-    .. code-block:: doscon
+   * Open **pgAdminIII**.
+   * Double-click the server to create a connection.
+   * Select :menuselection:`Edit --> New Object --> New Login Role`.
+   * Enter the username in the **Role Name** field (e.g. `odoo`).
+   * Open the **Definition** tab and enter the password (e.g. ``odoo``), then click **OK**.
 
-        C:\> cd \YourOdooPath
-        C:\YourOdooPath> C:\Python35\Scripts\pip.exe install -r requirements.txt
+Dependencies
+^^^^^^^^^^^^
 
-* *RTLCSS* via nodejs
+Odoo dependencies are listed in the `requirements.txt` file located at the root of the Odoo
+community directory. Most of them can be installed with **pip**.
 
-  For languages with right-to-left interface (such as Arabic or Hebrew), the
-  package ``rtlcss`` is needed.
+.. tip:: It can be preferable to not mix python modules packages between different instances of Odoo
+         or with your system. You can use virtualenv_ to create isolated Python environments.
 
-  - on Linux, use your distribution's package manager to install nodejs and
-    npm.
-    Once npm is installed, use it to install rtlcss:
+Navigate to the path of your Odoo Community installation (`YourOdooCommunityPath`) and run **pip**
+on the requirements file:
 
-    .. code-block:: console
+.. code-block:: doscon
 
-        $ sudo npm install -g rtlcss
+    C:\> cd \YourOdooCommunityPath
+    C:\YourOdooCommunityPath> C:\Python35\Scripts\pip.exe install -r requirements.txt
 
-  - on OS X, install nodejs via your preferred package manager (homebrew_,
-    macports_) then install less:
+.. warning:: Some dependencies cannot be installed through pip and require to be installed manually.
+             In particular:
 
-    .. code-block:: console
+             * `psycopg` must be installed with
+               `this installer <http://www.stickpeople.com/projects/python/win-psycopg/>`_.
+             * `wkhtmltopdf` must be installed in version `0.12.5 <the wkhtmltopdf download page_>`_
+               for it to support headers and footers. See our
+               `wiki <https://github.com/odoo/odoo/wiki/Wkhtmltopdf>`_ for more details on the
+               various versions.
 
-        $ sudo npm install -g rtlcss
+For languages with right-to-left interface (such as Arabic or Hebrew), the package `rtlcss` is
+needed:
 
-  - on Windows, `install nodejs <https://nodejs.org/en/download/>`_, reboot (to
-    update the :envvar:`PATH`) and install rtlcss:
+#. Download and install `nodejs <https://nodejs.org/en/download/>`_.
+#. Install `rtlcss`:
 
-    .. code-block:: doscon
+   .. code-block:: doscon
 
-        C:\> npm install -g rtlcss
+       C:\> npm install -g rtlcss
 
-    It is then necessary to edit the System Environment's variable
-    :envvar:`PATH` and add the folder where `rtlcss.cmd` is located. Typically:
+#. Edit the System Environment's variable `PATH` to add the folder where `rtlcss.cmd` is located
+   (typically: `C:\\Users\\<user>\\AppData\\Roaming\\npm\\`).
 
-    .. code-block:: console
+Running Odoo
+''''''''''''
 
-        C:\Users\<user>\AppData\Roaming\npm\
+Once all dependencies are set up, Odoo can be launched by running `odoo-bin`, the
+command-line interface of the server. It is located at the root of the Odoo Community directory.
 
+To configure the server, you can either specify :ref:`command-line arguments <reference/cmdline/server>` or a
+:ref:`configuration file <reference/cmdline/config>`.
 
-Fetch the sources
------------------
+.. tip:: For the Enterprise edition, you must add the path to the `enterprise` addons to the
+         `addons-path` argument. Note that it must come before the other paths in `addons-path` for
+         addons to be loaded correctly.
+
+Common necessary configurations are:
 
-There are two ways to obtain the Odoo source code: zip or git.
+* PostgreSQL user and password.
+* Custom addon paths beyond the defaults, to load your own modules.
+
+A typical way to run the server would be:
+
+.. code-block:: doscon
 
-* 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
+    C:\YourOdooCommunityPath> python3 odoo-bin -r dbuser -w dbpassword --addons-path=addons,../mymodules --db-filter=mydb$
 
-* 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.
+Where `YourOdooCommunityPath` is the path of the Odoo Community installation, `dbuser` is the
+PostgreSQL login, `dbpassword` is the PostgreSQL password, `../mymodules` is a directory with
+additional addons and `mydb` is the default database to serve on `localhost:8069`.
 
-Community Edition
+Linux
+-----
+
+Fetch the sources
 '''''''''''''''''
 
-The git repository is https://github.com/odoo/odoo.git for the Community
-edition.
+There are two ways to obtain the source code of Odoo: as a zip **archive** or through **git**.
+
+Archive
+^^^^^^^
+
+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:
+* `Official download page <download_>`_
+* `GitHub repository <community-repository_>`_
+* `Nightly server <nightly_>`_
+
+Enterprise Edition:
+
+* `Official download page <download_>`_
+* `GitHub repository <enterprise-repository_>`_
+
+Git
+^^^
+
+The following requires git_ to be installed on your machine and that you have basic knowledge of
+git commands.
+
+Community Edition:
 
 .. 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:
+Enterprise Edition: (see :ref:`setup/install/editions` to get access)
 
 .. 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.
+.. 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 Enterprise
+          installation.
 
-    You need to clone both the Community and Enterprise repository to have a working
-    Odoo installation
+Prepare
+'''''''
 
-Running Odoo
-------------
+Python
+^^^^^^
 
-Once all dependencies are set up, Odoo can be launched by running ``odoo-bin``.
+Odoo requires Python 3.5 or later to run. Use your package manager to download and install Python 3
+on your machine if it is not already done.
 
-.. 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
-    :file:`addons` folder in the  list for the addons to be loaded correctly.
+.. note:: If Python 3 is already installed, make sure that it is 3.5 or above, as previous versions
+          are not compatible with Odoo.
 
-:ref:`Configuration <reference/cmdline>` can be provided either through
-:ref:`command-line arguments <reference/cmdline>` or through a
-:ref:`configuration file <reference/cmdline/config>`.
+          .. code-block:: console
 
-Common necessary configurations are:
+              $ python3 --version
 
-* PostgreSQL host, port, user and password.
+          Verify also that pip_ is installed for this version.
 
-  Odoo has no defaults beyond
-  `psycopg2's defaults <http://initd.org/psycopg/docs/module.html>`_: connects
-  over a UNIX socket on port 5432 with the current user and no password. By
-  default this should work on Linux and OS X, but it *will not work* on
-  windows as it does not support UNIX sockets.
+          .. code-block:: console
 
-* Custom addons path beyond the defaults, to load your own modules
+              $ pip3 --version
 
-Under Windows a typical way to execute odoo would be:
+PostgreSQL
+^^^^^^^^^^
 
-.. code-block:: doscon
+Odoo uses PostgreSQL as database management system. Use your package manager to download and install
+the latest version of PostgreSQL.
+
+By default, the only user is `postgres` but Odoo forbids connecting as `postgres`, so you need to
+create a new PostgreSQL user:
 
-    C:\YourOdooPath> python3 odoo-bin -w odoo -r odoo --addons-path=addons,../mymodules --db-filter=mydb$
+.. code-block:: console
+
+  $ sudo -u postgres createuser -s $USER
+  $ createdb $USER
+
+.. note:: Because your PostgreSQL user has the same name as your Unix login, you will be able to
+          connect to the database without password.
 
-Where ``odoo``, ``odoo`` are the postgresql login and password,
-``../mymodules`` a directory with additional addons and ``mydb`` the default
-db to serve on localhost:8069
+Dependencies
+^^^^^^^^^^^^
 
-Under Unix a typical way to execute odoo would be:
+Odoo dependencies are listed in the `requirements.txt` file located at the root of the Odoo
+community directory. Most of them can be installed with **pip**.
+
+.. tip:: It can be preferable to not mix python modules packages between different instances of Odoo
+         or with your system. You can use virtualenv_ to create isolated Python environments.
+
+Navigate to the path of your Odoo Community installation (`YourOdooCommunityPath`) and run **pip**
+on the requirements file:
 
 .. code-block:: console
 
-    $ ./odoo-bin --addons-path=addons,../mymodules --db-filter=mydb$
+    $ cd /YourOdooCommunityPath
+    /YourOdooCommunityPath$ pip3 install -r requirements.txt
 
-Where ``../mymodules`` is a directory with additional addons and ``mydb`` the
-default db to serve on localhost:8069
+.. warning:: For libraries using native code (Pillow, lxml, greenlet, gevent, psycopg2, ldap), it
+             may be necessary to install development tools and native dependencies before pip is
+             able to install the dependencies themselves. These are available in `-dev` or `-devel`
+             packages for Python, PostgreSQL, libxml2, libxslt, libevent, libsasl2 and libldap2.
 
-Virtualenv
-----------
+.. warning:: Some dependencies cannot be installed through pip and require to be installed manually.
+             In particular:
 
-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.
+             * `wkhtmltopdf` must be installed in version `0.12.5 <the wkhtmltopdf download page_>`_
+               for it to support headers and footers. See our
+               `wiki <https://github.com/odoo/odoo/wiki/Wkhtmltopdf>`_ for more details on the
+               various versions.
 
-This section will explain how to run Odoo in a such isolated Python environment.
+For languages with right-to-left interface (such as Arabic or Hebrew), the package `rtlcss` is
+needed:
 
-Here we are going to use virtualenvwrapper_ which is a set of shell scripts that
-makes the use of virtualenv easier.
+#. Download and install **nodejs** and **npm** with your package manager.
+#. Install `rtlcss`:
 
-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.
+   .. code-block:: console
 
-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.
+       $ sudo npm install -g rtlcss
 
-Install virtualenvwrapper
-'''''''''''''''''''''''''
+Running Odoo
+''''''''''''
 
-.. code-block:: console
+Once all dependencies are set up, Odoo can be launched by running `odoo-bin`, the
+command-line interface of the server. It is located at the root of the Odoo Community directory.
+
+To configure the server, you can either specify :ref:`command-line arguments <reference/cmdline/server>` or a
+:ref:`configuration file <reference/cmdline/config>`.
 
-  $ sudo apt install virtualenvwrapper
-  $ source /usr/share/virtualenvwrapper/virtualenvwrapper.sh
+.. tip:: For the Enterprise edition, you must add the path to the `enterprise` addons to the
+         `addons-path` argument. Note that it must come before the other paths in `addons-path` for
+         addons to be loaded correctly.
 
-This will install virtualenvwrapper_ and activate it immediately.
-Now, let's install the tools required to build Odoo dependencies if needed:
+Common necessary configurations are:
+
+* PostgreSQL user and password. Odoo has no defaults beyond
+  `psycopg2's defaults <http://initd.org/psycopg/docs/module.html>`_: connects over a UNIX socket on
+  port `5432` with the current user and no password.
+* Custom addon paths beyond the defaults, to load your own modules.
+
+A typical way to run the server would be:
 
 .. code-block:: console
 
-  $ sudo apt install build-essential python3-dev libxslt-dev libzip-dev libldap2-dev libsasl2-dev
+    /YourOdooCommunityPath$ python3 odoo-bin --addons-path=addons,../mymodules --db-filter=mydb$
 
-Create an isolated environment
-''''''''''''''''''''''''''''''
+Where `YourOdooCommunityPath` is the path of the Odoo Community installation, `../mymodules` is a
+directory with additional addons and `mydb` is the default database to serve on `localhost:8069`.
 
-Now we can create a virtual environment for Odoo like this:
+Mac OS
+------
 
-.. code-block:: console
+Fetch the sources
+'''''''''''''''''
+
+There are two ways to obtain the source code of Odoo: as a zip **archive** or through **git**.
+
+Archive
+^^^^^^^
+
+Community Edition:
 
-  $ mkvirtualenv -p /usr/bin/python3 odoo-venv
+* `Official download page <download_>`_
+* `GitHub repository <community-repository_>`_
+* `Nightly server <nightly_>`_
 
-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:
+Enterprise Edition:
+
+* `Official download page <download_>`_
+* `GitHub repository <enterprise-repository_>`_
+
+Git
+^^^
+
+The following requires git_ to be installed on your machine and that you have basic knowledge of
+git commands.
+
+Community Edition:
 
 .. code-block:: console
 
-  $ which python3
+    $ git clone https://github.com/odoo/odoo.git
 
-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:
+Enterprise Edition: (see :ref:`setup/install/editions` to get access)
 
 .. code-block:: console
 
-  $ cd your_odoo_sources_path
-  $ pip install -r requirements.txt
+  $ 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 Enterprise
+          installation.
+
+Prepare
+'''''''
+
+Python
+^^^^^^
+
+Odoo requires Python 3.5 or later to run. Use your preferred package manager (homebrew_, macports_)
+to download and install Python 3 on your machine if it is not already done.
+
+.. note:: If Python 3 is already installed, make sure that it is 3.5 or above, as previous versions
+          are not compatible with Odoo.
 
-After a little while, you should be ready to run odoo from the command line as
-explained above.
+          .. code-block:: console
 
-When you you want to leave the virtual environment, just issue this command:
+              $ python3 --version
+
+          Verify also that pip_ is installed for this version.
+
+          .. code-block:: console
+
+              $ pip3 --version
+
+PostgreSQL
+^^^^^^^^^^
+
+Odoo uses PostgreSQL as database management system. Use `postgres.app <https://postgresapp.com>`_
+to download and install the latest version of PostgreSQL.
+
+By default, the only user is `postgres` but Odoo forbids connecting as `postgres`, so you need to
+create a new PostgreSQL user:
 
 .. code-block:: console
 
-  $ deactivate
+  $ sudo -u postgres createuser -s $USER
+  $ createdb $USER
 
-Whenever you want to work again with your 'odoo-venv' environment:
+.. note:: Because your PostgreSQL user has the same name as your Unix login, you will be able to
+          connect to the database without password.
+
+Dependencies
+^^^^^^^^^^^^
+
+Odoo dependencies are listed in the `requirements.txt` file located at the root of the Odoo
+community directory. Most of them can be installed with **pip**.
+
+.. tip:: It can be preferable to not mix python modules packages between different instances of Odoo
+         or with your system. You can use virtualenv_ to create isolated Python environments.
+
+Navigate to the path of your Odoo Community installation (`YourOdooCommunityPath`) and run **pip**
+on the requirements file:
 
 .. code-block:: console
 
-  $ workon odoo-venv
+   $ cd /YourOdooCommunityPath
+   /YourOdooCommunityPath$ pip3 install -r requirements.txt
+
+.. warning:: Non-Python dependencies need to be installed with a package manager:
+
+             #. Download and install the **Command Line Tools**:
+
+                .. code-block:: console
+
+                   $ xcode-select --install
+
+             #. Download and install the package manager of your choice (homebrew_, macports_).
+             #. Install non-python dependencies.
+
+.. warning:: Some dependencies cannot be installed through pip and require to be installed manually.
+             In particular:
+
+             * `wkhtmltopdf` must be installed in version `0.12.5 <the wkhtmltopdf download page_>`_
+               for it to support headers and footers. See our
+               `wiki <https://github.com/odoo/odoo/wiki/Wkhtmltopdf>`_ for more details on the
+               various versions.
+
+For languages with right-to-left interface (such as Arabic or Hebrew), the package `rtlcss` is
+needed:
+
+#. Download and install **nodejs** with your preferred package manager (homebrew_, macports_).
+#. Install `rtlcss`:
+
+   .. code-block:: console
+
+       $ sudo npm install -g rtlcss
+
 
 .. _setup/install/docker:
 
@@ -580,18 +734,16 @@ Docker
 The full documentation on how to use Odoo with Docker can be found on the
 official Odoo `docker image <https://registry.hub.docker.com/_/odoo/>`_ page.
 
+.. _Debian Stretch: https://www.debian.org/releases/stretch/
 .. _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/
+.. _download: https://www.odoo.com/page/download
 .. _Ubuntu 18.04: http://releases.ubuntu.com/18.04/
 .. _EPEL: https://fedoraproject.org/wiki/EPEL
 .. _PostgreSQL: http://www.postgresql.org
 .. _the official installer:
 .. _install pip:
     https://pip.pypa.io/en/latest/installing.html#install-pip
-.. _PostgreSQL for windows:
-    http://www.enterprisedb.com/products-services-training/pgdownload
 .. _Quilt: http://en.wikipedia.org/wiki/Quilt_(software)
 .. _saas: https://www.odoo.com/page/start
 .. _the wkhtmltopdf download page: https://github.com/wkhtmltopdf/wkhtmltopdf/releases/tag/0.12.5
@@ -604,8 +756,9 @@ official Odoo `docker image <https://registry.hub.docker.com/_/odoo/>`_ page.
 .. _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
+.. _community-repository: https://github.com/odoo/odoo
+.. _enterprise-repository: https://github.com/odoo/enterprise
+.. _git: https://git-scm.com/
 .. _Editions: https://www.odoo.com/pricing#pricing_table_features
-.. _nightly: https://nightly.odoo.com/12.0/nightly/
+.. _nightly: https://nightly.odoo.com/
 .. _extra: https://nightly.odoo.com/extra/