From f04f409943b8bd8f4bd2653e368523d1cc0d8246 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@odoo.com>
Date: Mon, 15 Dec 2014 15:55:34 +0100
Subject: [PATCH] [ADD] doc: setup documentation

* Odoo installation from packages or source
* Deployment instructions for production environments
* dbfilter

Add missing support for disabling xmlrpc(/http), useful for WSGI
deployments which require running cron-only Odoo instances.
---
 doc/howtos/backend.rst    |   4 +
 doc/howtos/web.rst        |   2 +-
 doc/howtos/website.rst    |   2 +-
 doc/index.rst             |   1 +
 doc/reference/cmdline.rst | 246 +++++++++++++++++++++++++--
 doc/setup.rst             |   9 +
 doc/setup/deploy.rst      | 246 +++++++++++++++++++++++++++
 doc/setup/install.rst     | 348 ++++++++++++++++++++++++++++++++++++++
 openerp/service/server.py |  11 +-
 openerp/tools/config.py   |   6 +-
 10 files changed, 848 insertions(+), 27 deletions(-)
 create mode 100644 doc/setup.rst
 create mode 100644 doc/setup/deploy.rst
 create mode 100644 doc/setup/install.rst

diff --git a/doc/howtos/backend.rst b/doc/howtos/backend.rst
index e1ba28e3324..fcbc10e3721 100644
--- a/doc/howtos/backend.rst
+++ b/doc/howtos/backend.rst
@@ -4,6 +4,10 @@
 Building a Module
 =================
 
+.. warning::
+
+    This tutorial requires :ref:`having installed Odoo <setup/install>`
+
 Start/Stop the Odoo server
 ==========================
 
diff --git a/doc/howtos/web.rst b/doc/howtos/web.rst
index ba8337ffd34..2fe16cd3a2d 100644
--- a/doc/howtos/web.rst
+++ b/doc/howtos/web.rst
@@ -19,7 +19,7 @@ or extend existing business systems of Odoo, see :doc:`backend`.
     * jQuery_
     * `Underscore.js`_
 
-    It also requires an installed Odoo, and Git_.
+    It also requires :ref:`an installed Odoo <setup/install>`, and Git_.
 
 
 A Simple Module
diff --git a/doc/howtos/website.rst b/doc/howtos/website.rst
index 5092cac5df6..6ec9fddc76c 100644
--- a/doc/howtos/website.rst
+++ b/doc/howtos/website.rst
@@ -8,7 +8,7 @@ Building a Website
 
     * This guide assumes `basic knowledge of Python
       <http://docs.python.org/2/tutorial/>`_
-    * This guide assumes an installed Odoo
+    * This guide assumes :ref:`an installed Odoo <setup/install>`
 
 Creating a basic module
 =======================
diff --git a/doc/index.rst b/doc/index.rst
index 45394cdfd58..3bb952e4383 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -11,6 +11,7 @@ Odoo Technical Documentation
     :maxdepth: 2
 
     tutorials
+    setup
     reference
     api_integration
 
diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst
index e0713410981..269f62ed2eb 100644
--- a/doc/reference/cmdline.rst
+++ b/doc/reference/cmdline.rst
@@ -11,36 +11,83 @@ Running the server
 
 .. program:: odoo.py
 
-.. option:: -d <database>, --database=<database>
+.. option:: -d <database>, --database <database>
 
     database used when installing or updating modules.
 
-.. option:: --db-filter=<filter>
-
-    hides databases that do not match ``<filter>``. The filter is a
-    `regular expression`_, with the additions that:
-
-    - ``%h`` is replaced by the whole hostname the request is made on.
-    - ``%d`` is replaced by the subdomain the request is made on, with the
-      exception of ``www`` (so domain ``odoo.com`` and ``www.odoo.com`` both
-      match the database ``odoo``)
-
-.. option:: -i <modules>, --init=<modules>
+.. option:: -i <modules>, --init <modules>
 
     comma-separated list of modules to install before running the server
     (requires :option:`-d`).
 
-.. option:: -u <modules>, --update=<modules>
+.. option:: -u <modules>, --update <modules>
 
     comma-separated list of modules to update before running the server
     (requires :option:`-d`).
 
-.. option:: --addons-path=<directories>
+.. option:: --addons-path <directories>
 
     comma-separated list of directories in which modules are stored. These
     directories are scanned for modules (nb: when and why?)
 
-.. option:: -c <config>, --config=<config>
+.. option:: --workers <count>
+
+    if ``count`` is not 0 (the default), enables multiprocessing and sets up
+    the specified number of HTTP workers (sub-processes processing HTTP
+    and RPC requests).
+
+    .. note:: multiprocessing mode is only available on Unix-based systems
+
+    A number of options allow limiting and recyling workers:
+
+    .. option:: --limit-request <limit>
+
+        Number of requests a worker will process before being recycled and
+        restarted.
+
+        Defaults to 8196.
+
+    .. option:: --limit-memory-soft <limit>
+
+        Maximum allowed virtual memory per worker. If the limit is exceeded,
+        the worker is killed and recycled at the end of the current request.
+
+        Defaults to 640MB.
+
+    .. option:: --limit-memory-hard <limit>
+
+        Hard limit on virtual memory, any worker exceeding the limit will be
+        immediately killed without waiting for the end of the current request
+        processing.
+
+        Defaults to 768MB.
+
+    .. option:: --limit-time-cpu <limit>
+
+        Prevents the worker from using more than <limit> CPU seconds for each
+        request. If the limit is exceeded, the worker is killed.
+
+        Defaults to 60.
+
+    .. option:: --limit-time-real <limit>
+
+        Prevents the worker from taking longer than <limit> seconds to process
+        a request. If the limit is exceeded, the worker is killed.
+
+        Differs from :option:`--limit-time-cpu` in that this is a "wall time"
+        limit including e.g. SQL queries.
+
+        Defaults to 120.
+
+.. option:: --max-cron-threads <count>
+
+    number of workers dedicated to cron jobs. Defaults to 2. The workers are
+    threads in multithreading mode and processes in multiprocessing mode.
+
+    For multiprocessing mode, this is in addition to the HTTP worker
+    processes.
+
+.. option:: -c <config>, --config <config>
 
     provide an alternate configuration file
 
@@ -50,6 +97,14 @@ Running the server
     (:file:`{$HOME}/.openerp_serverrc` by default, overridable using
     :option:`-c`)
 
+.. option:: --proxy-mode
+
+    enables the use of ``X-Forwarded-*`` headers through `Werkzeug's proxy
+    support`_.
+
+    .. warning:: proxy mode *must not* be enabled outside of a reverse proxy
+                 scenario
+
 .. option:: --test-enable
 
     runs tests after installing modules
@@ -60,6 +115,140 @@ Running the server
     automatically starts :mod:`python:pdb` before logging and returning the
     error
 
+.. _reference/cmdline/server/database:
+
+database
+--------
+
+.. option:: -r <user>, --db_user <user>
+
+    database username, used to connect to PostgreSQL.
+
+.. option:: -w <password>, --db_password <password>
+
+    database password, if using `password authentication`_.
+
+.. option:: --db_host <hostname>
+
+    host for the database server
+
+    * ``localhost`` on Windows
+    * UNIX socket otherwise
+
+.. option:: --db_port <port>
+
+    port the database listens on, defaults to 5432
+
+.. option:: --db-filter <filter>
+
+    hides databases that do not match ``<filter>``. The filter is a
+    `regular expression`_, with the additions that:
+
+    - ``%h`` is replaced by the whole hostname the request is made on.
+    - ``%d`` is replaced by the subdomain the request is made on, with the
+      exception of ``www`` (so domain ``odoo.com`` and ``www.odoo.com`` both
+      match the database ``odoo``)
+
+.. option:: --db-template <template>
+
+    when creating new databases from the database-management screens, use the
+    specified `template database`_. Defaults to ``template1``.
+
+built-in HTTP
+-------------
+
+.. option:: --no-xmlrpc
+
+    do not start the HTTP or long-polling workers (may still start cron
+    workers)
+
+    .. warning:: has no effect if :option:`--test-enable` is set, as tests
+                 require an accessible HTTP server
+
+.. option:: --xmlrpc-interface <interface>
+
+    TCP/IP address on which the HTTP server listens, defaults to ``0.0.0.0``
+    (all addresses)
+
+.. option:: --xmlrpc-port <port>
+
+    Port on which the HTTP server listens, defaults to 8069.
+
+.. option:: --longpolling-port <port>
+
+    TCP port for long-polling connections in multiprocessing or gevent mode,
+    defaults to 8072. Not used in default (threaded) mode.
+
+logging
+-------
+
+By default, Odoo displays all logging of level_ ``info`` except for workflow
+logging (``warning`` only), and log output is sent to ``stdout``. Various
+options are available to redirect logging to other destinations and to
+customize the amout of logging output
+
+.. option:: --logfile <file>
+
+    sends logging output to the specified file instead of stdout. On Unix, the
+    file `can be managed by external log rotation programs
+    <https://docs.python.org/2/library/logging.handlers.html#watchedfilehandler>`_
+    and will automatically be reopened when replaced
+
+.. option:: --logrotate
+
+    enables `log rotation <https://docs.python.org/2/library/logging.handlers.html#timedrotatingfilehandler>`_
+    daily, keeping 30 backups. Log rotation frequency and number of backups is
+    not configurable.
+
+.. option:: --syslog
+
+    logs to the system's event logger: `syslog on unices <https://docs.python.org/2/library/logging.handlers.html#sysloghandler>`_
+    and `the Event Log on Windows <https://docs.python.org/2/library/logging.handlers.html#nteventloghandler>`_.
+
+    Neither is configurable
+
+.. option:: --log-db <dbname>
+
+    logs to the ``ir.logging`` model (``ir_logging`` table) of the specified
+    database. The database can be the name of a database in the "current"
+    PostgreSQL, or `a PostgreSQL URI`_ for e.g. log aggregation
+
+.. option:: --log-handler <handler-spec>
+
+    :samp:`{LOGGER}:{LEVEL}`, enables ``LOGGER`` at the provided ``LEVEL``
+    e.g. ``openerp.models:DEBUG`` will enable all logging messages at or above
+    ``DEBUG`` level in the models.
+
+    * The colon ``:`` is mandatory
+    * The logger can be omitted to configure the root (default) handler
+    * If the level is omitted, the logger is set to ``INFO``
+
+    The option can be repeated to configure multiple loggers e.g.
+
+    .. code-block:: console
+
+        $ odoo.py --log-handler :DEBUG --log-handler werkzeug:CRITICAL --log-handler openerp.fields:WARNING
+
+.. option:: --log-request
+
+    enable DEBUG logging for RPC requests, equivalent to
+    ``--log-handler=openerp.http.rpc.request:DEBUG``
+
+.. option:: --log-response
+
+    enable DEBUG logging for RPC responses, equivalent to
+    ``--log-handler=openerp.http.rpc.response:DEBUG``
+
+.. option:: --log-web
+
+    enables DEBUG logging of HTTP requests and responses, equivalent to
+    ``--log-handler=openerp.http:DEBUG``
+
+.. option:: --log-sql
+
+    enables DEBUG logging of SQL querying, equivalent to
+    ``--log-handler=openerp.sql_db:DEBUG``
+
 .. _reference/cmdline/scaffold:
 
 Scaffolding
@@ -95,7 +284,22 @@ Configuration file
 ==================
 
 Most of the command-line options can also be specified via a configuration
-file.
+file. Most of the time, they use similar names with the prefix ``-`` removed
+and other ``-`` are replaced by ``_`` e.g. :option:`--db-template` becomes
+``db_template``.
+
+Some conversions don't match the pattern:
+
+* :option:`--db-filter` becomes ``dbfilter``
+* :option:`--no-xmlrpc` corresponds to the ``xmlrpc`` boolean
+* logging presets (all options starting with ``--log-`` except for
+  :option:`--log-handler` and :option:`--log-db`) just add content to
+  ``log_handler``, use that directly in the configuration file
+* :option:`--smtp` is stored as ``smtp_server``
+* :option:`--database` is stored as ``dbname``
+* :option:`--debug` is stored as ``debug_mode`` (a boolean)
+* :option:`--i18n-import` and :option:`--i18n-export` aren't available at all
+  from configuration files
 
 The default configuration file is :file:`{$HOME}/.openerp_serverrc` which
 can be overridden using :option:`--config <odoo.py -c>`. Specifying
@@ -104,3 +308,13 @@ to that file.
 
 .. _jinja2: http://jinja.pocoo.org
 .. _regular expression: https://docs.python.org/2/library/re.html
+.. _password authentication:
+    http://www.postgresql.org/docs/9.3/static/auth-methods.html#AUTH-PASSWORD
+.. _template database:
+    http://www.postgresql.org/docs/9.3/static/manage-ag-templatedbs.html
+.. _level:
+    https://docs.python.org/2/library/logging.html#logging.Logger.setLevel
+.. _a PostgreSQL URI:
+    http://www.postgresql.org/docs/9.2/static/libpq-connect.html#AEN38208
+.. _Werkzeug's proxy support:
+    http://werkzeug.pocoo.org/docs/0.9/contrib/fixers/#werkzeug.contrib.fixers.ProxyFix
diff --git a/doc/setup.rst b/doc/setup.rst
new file mode 100644
index 00000000000..0d6b7e1b1d0
--- /dev/null
+++ b/doc/setup.rst
@@ -0,0 +1,9 @@
+==========
+Setting Up
+==========
+
+.. toctree::
+    :titlesonly:
+
+    setup/install
+    setup/deploy
diff --git a/doc/setup/deploy.rst b/doc/setup/deploy.rst
new file mode 100644
index 00000000000..dc462dcf640
--- /dev/null
+++ b/doc/setup/deploy.rst
@@ -0,0 +1,246 @@
+==============
+Deploying Odoo
+==============
+
+This document describes basic steps to set up Odoo in production. It follows
+:ref:`installation <setup/install>`, but should not be used for development
+systems.
+
+dbfilter
+========
+
+Odoo is a multi-tenant system: a single Odoo system may run and serve a number
+of database instances. It is also highly customizable, with customizations
+(starting from the modules being loaded) depending on the "current database".
+
+This is not an issue when working with the backend (web client) as a logged-in
+company user: the database can be selected when logging in, and customizations
+loaded afterwards.
+
+However it is an issue for non-logged users (portal, website) which aren't
+bound to a database: Odoo need to know which database should be used for the
+operations or to get the data. If multi-tenancy is not used that is not an
+issue, there's only one database to use, but if there are multiple databases
+accessible Odoo needs a rule to know which one it should use.
+
+That is one of the purposes of :option:`--db-filter <odoo.py --db-filter>`:
+it specifies the default database for the Odoo system. The value is a
+`regular expression`_, possibly including the dynamically injected hostname
+or subdomain through which the Odoo system is accessed.
+
+If an Odoo hosts multiple databases in production, especially if ``website``
+is used, it **must** use a dbfilter or a number of features will not work
+correctly or not use at all.
+
+PostgreSQL
+==========
+
+By default, PostgreSQL only allows connection over UNIX sockets and loopback
+connections (from "localhost", the same machine the PostgreSQL server is
+installed on).
+
+UNIX socket is fine if you want Odoo and PostgreSQL to execute on the same
+machine, and the default when no host is provided, but if you want Odoo and
+PostgreSQL to execute on different machines [#different-machines]_ it will
+need to `listen to network interfaces`_ [#remote-socket]_, either:
+
+* only accept loopback connections and `use an SSH tunnel`_ between the
+  machine on which Odoo runs and the one on which PostgreSQL runs, then
+  configure Odoo to connect to its end of the tunnel
+* accept connections to the machine on which Odoo is installed, possibly with
+  over ssl (see `PostgreSQL connection settings`_ for details), then configure
+  Odoo to connect over the network
+
+.. _setup/deploy/odoo:
+
+Configuring Odoo
+----------------
+
+Out of the box, Odoo connects to a local postgres over UNIX socket via port
+5432. This can be overridden using :ref:`the database options
+<reference/cmdline/server/database>` when your Postgres deployment is not
+local and/or does not use the installation defaults.
+
+The :ref:`packaged installers <setup/install/packaged>` will automatically
+create a new user (``odoo``) and set it as the database user.
+
+* The database management screens are protected by the ``admin_passwd``
+  setting. This setting can only be set using configuration files, and is
+  simply checked before performing database alterations. It should be set to
+  a randomly generated value to ensure third parties can not use this
+  interface.
+* all database operations use the :ref:`database options
+  <reference/cmdline/server/database>`, including the database management
+  screen. For the database management screen to work requires that the user
+  have ``createdb`` right.
+* users can always drop databases they own. For the database management screen
+  to be completely non-functional, the user needs to be created with
+  ``no-createdb`` and the database must be owned by a different user.
+
+  .. warning:: the user also needs to *not* be a superuser
+
+HTTPS
+=====
+
+Whether it's accessed via website/web client or the webservice, Odoo transmits
+authentication information in cleatext. This means a secure deployment of
+Odoo must use HTTPS\ [#switching]_. SSL termination can be implemented via
+just about any SSL termination proxy, but requires the following setup:
+
+* enable Odoo's :option:`proxy mode <odoo.py --proxy-mode>`. This should only
+  be enabled when Odoo is behind a reverse proxy
+* set up the SSL termination proxy (`Nginx termination example`_)
+* set up the proxying itself (`Nginx proxying example`_)
+* your SSL termination proxy should also automatically redirect non-secure
+  connections to the secure port
+
+Builtin server
+==============
+
+Odoo includes built-in HTTP servers, using either multithreading or
+multiprocessing.
+
+For production use, it is recommended to use the multiprocessing server as it
+increases stability, makes somewhat better use of computing resources and can
+be better monitored and resource-restricted.
+
+* Multiprocessing is enabled by configuring :option:`a non-zero number of
+  worker processes <odoo.py --workers>`, the number of workers should be based
+  on the number of cores in the machine (possibly with some room for cron
+  workers depending on how much cron work is predicted)
+* Worker limits can be configured based on the hardware configuration to avoid
+  resources exhaustion
+
+.. warning:: multiprocessing mode currently isn't available on Windows
+
+LiveChat
+--------
+
+In multiprocessing, a dedicated LiveChat worker is automatically started and
+listening on :option:`the longpolling port <odoo.py --longpolling-port>` but
+the client will not connect to it.
+
+Instead you must have a proxy redirecting requests whose URL starts with
+``/longpolling/`` to the longpolling port. Other request should be proxied to
+the :option:`normal HTTP port <odoo.py --xmlrpc-port>`
+
+Odoo as a WSGI Application
+==========================
+
+It is also possible to mount Odoo as a standard WSGI_ application. Odoo
+provides the base for a WSGI launcher script as ``openerp-wsgi.py``. That
+script should be customized (possibly after copying it) to correctly set the
+configuration directly in :mod:`openerp.tools.config` rather than through the
+command-line or a configuration file.
+
+However the WSGI server will only expose the main HTTP endpoint for the web
+client, website and webservice API. Because Odoo does not control the creation
+of workers anymore it can not setup cron or livechat workers
+
+Cron Workers
+------------
+
+To run cron jobs for an Odoo deployment as a WSGI application requires
+
+* a classical Odoo (run via ``odoo.py``)
+* connected to the database in which cron jobs have to be run (via
+  :option:`odoo.py -d`)
+* which should not be exposed to the network. To ensure cron runners are not
+  network-accessible, it is possible to disable the built-in HTTP server
+  entirely with :option:`odoo.py --no-xmlrpc` or setting ``xmlrpc = False``
+  in the configuration file
+
+LiveChat
+--------
+
+The second problematic subsystem for WSGI deployments is the LiveChat: where
+most HTTP connections are relatively short and quickly free up their worker
+process for the next request, LiveChat require a long-lived connection for
+each client in order to implement near-real-time notifications.
+
+This is in conflict with the process-based worker model, as it's going to tie
+up worker processes and prevent new users from accessing the system. However,
+those long-lived connections do very little and mostly stay parked waiting for
+notifications.
+
+The solutions to support livechat/motifications in a WSGI application are:
+
+* deploy a threaded version of Odoo (instread of a process-based preforking
+  one) and redirect only requests to URLs starting with ``/longpolling/`` to
+  that Odoo, this is the simplest and the longpolling URL can double up as
+  the cron instance.
+* deploy an evented Odoo via ``openerp-gevent`` and proxy requests starting
+  with ``/longpolling/`` to
+  :option:`the longpolling port <odoo.py --longpolling-port>`.
+
+Serving Static Files
+====================
+
+For development convenience, Odoo directly serves all static files in its
+modules. This may not be ideal when it comes to performances, and static
+files should generally be served by a static HTTP server.
+
+Odoo static files live in each module's ``static/`` folder, so static files
+can be served by intercepting all requests to :samp:`/{MODULE}/static/{FILE}`,
+and looking up the right module (and file) in the various addons paths.
+
+.. todo:: test whether it would be interesting to serve filestored attachments
+          via this, and how (e.g. possibility of mapping ir.attachment id to
+          filestore hash in the database?)
+
+Security
+========
+
+"Super-admin" password
+----------------------
+
+:ref:`setup/deploy/odoo` mentioned ``admin_passwd`` in passing.
+
+This setting is used on all database management screens (to create, delete,
+dump or restore databases).
+
+If the management screens must not be accessible, or must only be accessible
+from a selected set of machines, use the proxy server's features to block
+access to all routes starting with ``/web/database`` except (maybe)
+``/web/database/selector`` which displays the database-selection screen.
+
+If the database-management screen should be left accessible, the
+``admin_passwd`` setting must be changed from its ``admin`` default: this
+password is checked before allowing database-alteration operations.
+
+It should be stored securely, and should be generated randomly e.g.
+
+.. code-block:: console
+
+    $ python -c 'import base64, os; print(base64.b64encode(os.urandom(24)))'
+
+which will generate a 32 characters pseudorandom printable string.
+
+.. [#different-machines]
+    to have multiple Odoo installations use the same PostgreSQL database,
+    or to provide more computing resources to both software.
+.. [#remote-socket]
+    technically a tool like socat_ can be used to proxy UNIX sockets across
+    networks, but that is mostly for software which can only be used over
+    UNIX sockets
+.. [#switching]
+    or be accessible only over an internal packet-switched network, but that
+    requires secured switches, protections against `ARP spoofing`_ and
+    precludes usage of WiFi. Even over secure packet-switched networks,
+    deployment over HTTPS is recommended, and possible costs are lowered as
+    "self-signed" certificates are easier to deploy on a controlled
+    environment than over the internet.
+
+.. _regular expression: https://docs.python.org/2/library/re.html
+.. _ARP spoofing: http://en.wikipedia.org/wiki/ARP_spoofing
+.. _Nginx termination example:
+    http://nginx.com/resources/admin-guide/nginx-ssl-termination/
+.. _Nginx proxying example:
+    http://nginx.com/resources/admin-guide/reverse-proxy/
+.. _socat: http://www.dest-unreach.org/socat/
+.. _PostgreSQL connection settings:
+.. _listen to network interfaces:
+    http://www.postgresql.org/docs/9.3/static/runtime-config-connection.html
+.. _use an SSH tunnel:
+    http://www.postgresql.org/docs/9.3/static/ssh-tunnels.html
+.. _WSGI: http://wsgi.readthedocs.org/
diff --git a/doc/setup/install.rst b/doc/setup/install.rst
new file mode 100644
index 00000000000..f4758c1281f
--- /dev/null
+++ b/doc/setup/install.rst
@@ -0,0 +1,348 @@
+.. _setup/install:
+
+===============
+Installing Odoo
+===============
+
+There are mutliple ways to install Odoo, or not install it at all, depending
+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, but restricts the
+    flexibility of the system somewhat (check: no custom modules? what else?).
+
+    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.
+
+    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.
+:ref:`setup/install/vcs`
+    Mostly has the same strengths and weaknesses as the
+    :ref:`setup/install/source`, but allows (technically) simpler
+    switching between versions of Odoo, as well as more structured patching
+    and customisations of Odoo itself (not through custom modules): with a
+    standard :ref:`setup/install/source`, a custom solution has to be
+    implemented to keep track of patches applied to Odoo (e.g. Quilt_). With
+    a VCS checkout, these changes can be implemented as standard Git revisions
+    or a custom Git branch, and can more easily be contributed back to the
+    main project.
+
+.. _setup/install/demo:
+
+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
+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.
+
+Like demo_ instances, SaaS_ instances require no local installation, a web
+browser is sufficient.
+
+.. _setup/install/packaged:
+
+Packaged installers
+===================
+
+.. Odoo provides packaged installers for Windows, deb-based distributions
+.. (Debian, Ubuntu, …) and RPM-based distributions (Fedora, CentOS, RHEL, …).
+
+Odoo provides packaged installers for Windows and deb-based distributions
+(Debian, Ubuntu, …).
+
+These packages automatically set up all dependencies, but may be difficult to
+keep up-to-date.
+
+Official packages with all relevant dependency requirements are available on
+https://nightly.odoo.com.
+
+Deb
+---
+
+To install Odoo 8.0 on Debian-based distribution, execute the following
+commands as root:
+
+.. code-block:: console
+
+    # wget -O - https://nightly.odoo.com/odoo.key | apt-key add -
+    # echo "deb http://nightly.odoo.com/8.0/nightly/deb/ ./" >> /etc/apt/sources.list
+    # apt-get update && apt-get install odoo
+
+This will automatically install all dependencies, install Odoo itself as a
+daemon and automatically start it.
+
+.. postgres-server apparently automatically installed due to being a
+   recommended package, maybe install it explicitly for the purpose of this
+   document?
+
+.. 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. Use the version available on
+            `the wkhtmltopdf download page`_.
+
+Configuration
+'''''''''''''
+
+The :ref:`configuration file <reference/cmdline/config>` can be found at
+:file:`/etc/odoo/openerp-server.conf`
+
+When the configuration file is edited, Odoo must be restarted using
+``service``:
+
+.. code-block:: console
+
+    $ sudo service odoo restart
+    Restarting odoo: ok
+
+RPM
+---
+
+.. warning::
+
+    with RHEL-based distributions (RHEL, CenOS, Scientific Linux), EPEL_ must
+    be added to the distribution's repositories for all of Odoo's
+    dependencies to be available. For CenOS:
+
+    .. code-block:: console
+
+        $ sudo yum install -y epel-release
+
+    For other RHEL-based distribution, see the EPEL_ documentation.
+
+.. code-block:: console
+
+    $ sudo yum install -y postgresql-server
+    $ sudo postgresql-setup initdb
+    $ sudo systemctl enable postgresql
+    $ sudo systemctl start postgresql
+    $ sudo yum-config-manager --add-repo=https://nightly.odoo.com/8.0/nightly/rpm/odoo.repo
+    $ sudo yum install -y odoo
+    $ sudo systemctl enable odoo
+    $ sudo systemctl start odoo
+
+.. 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
+'''''''''''''
+
+The :ref:`configuration file <reference/cmdline/config>` can be found at
+:file:`/etc/odoo/openerp-server.conf`
+
+When the configuration file is edited, Odoo must be restarted via SystemD:
+
+.. code-block:: console
+
+    $ sudo systemctl restart odoo
+
+Windows
+-------
+
+* download https://nightly.odoo.com/8.0/nightly/exe/odoo_8.0.latest.exe
+* run the downloaded file
+
+  .. warning:: on Windows 8, you may see a warning titled "Windows protected
+               your PC". Click :guilabel:`More Info` then
+               :guilabel:`Run anyway`
+
+* Accept the UAC_ prompt
+* Go through the various installation steps
+
+Odoo will automatically be started at the end of the installation.
+
+Configuration
+'''''''''''''
+
+The :ref:`configuration file <reference/cmdline/config>` can be found at
+:file:`{%PROGRAMFILES%}\\Odoo 8.0-{id}\\server\\openerp-server.conf`.
+
+The configuration file can be edited to connect to a remote Postgresql, edit
+file locations or set a dbfilter.
+
+To reload the configuration file, restart the Odoo service via
+:menuselection:`Services --> odoo server`.
+
+.. _setup/install/source:
+
+Source Install
+==============
+
+The source "installation" really is 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).
+
+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.
+
+The Odoo source can be downloaded from
+https://nightly.odoo.com/8.0/nightly/src/odoo_8.0-latest.tar.gz
+
+.. warning:: Windows does not handle .tar.gz archives natively, you will have
+             to download and install `7-Zip <http://www.7-zip.org>`_ to
+             decompress the archive
+
+Installing dependencies
+-----------------------
+
+Source installation requires manually installing dependencies, be them native
+dependencies or Python libraries:
+
+* Python, should be preinstalled on most systems. On Windows, use `the
+  official Python 2.7 installer <https://www.python.org/downloads/windows/>`_.
+
+* PostgreSQL, if you want the database to be on the same machine as Odoo
+  (simplest and default)
+
+  - on Linux, use your distribution's package
+  - on Windows, use `the official installer`_
+  - on OS X, `postgres.app <http://postgresapp.com>`_ is the simplest way to
+    get started
+
+  .. todo:: create new role?
+
+* the :file:`requirements.txt` file in the source lists all the Python
+  dependencies
+
+  - for Windows, http://www.lfd.uci.edu/~gohlke/pythonlibs/ provides a number
+    of libraries, for both pure-python and native, packaged as installers
+  - dependencies may be installable with the system's package manager
+  - pip_ can take the requirements file directly and install everything listed
+    in it, either globally or within a `virtual environment`_:
+
+    .. code-block:: console
+
+        $ pip install -r path/to/requirements.txt
+
+    For libraries using native code (Pillow, lxml, greenlet, gevent, psycopg2)
+    it may be necessary to install development tools and native dependencies
+    before pip is able to install the dependencies themselves:
+
+    * Linux distributions generally require ``-dev`` or ``-devel`` packages
+      for Python, Postgres, libxml2, libxslt and libevent
+    * for OSX, install the Command Line Tools (``xcode-select --install``) the
+      native dependency via your preferred package manager (macports_,
+      homebrew_)
+    * for Windows
+
+      .. danger:: you will have to remove ``python-ldap`` from the
+                  requirements file, it can not be installed via pip_ on
+                  Windows and must be installed as a precompiled binary
+
+      - install the `Visual C++ Compiler for Python 2.7`_ (and restart)
+      - install `PostgreSQL for windows`_ if not already done
+      - Add PostgreSQL's ``bin`` directory (default:
+        ``C:\Program Files\PostgreSQL\9.3\bin``) to your :envvar:`PATH`
+
+      ``greenlet``, ``Pillow`` and ``lxml`` are available as pre-compiled
+      wheels_ and trivially installed by pip_, ``gevent`` only needs the
+      compiler to be installable and a local installation ``psycopg2``
+
+      .. note:: by default, Python scripts are not on the PATH in windows,
+                after installing pip_ add ``C:\Python27\Scripts`` to your
+                :envvar:`PATH`
+
+.. danger:: whatever the installation method, Odoo on Windows also needs
+            pywin32_ which is not listed in the requirements file. It can be
+            installed using pip_ with ``pip install pypiwin32``, or manually
+            by downloading the official pywin32_ installer and running it.
+
+Running Odoo
+------------
+
+Once all dependencies are set up, Odoo can be launched by running ``odoo.py``.
+
+:ref:`Configuration <reference/cmdline>` can be provided either through
+:ref:`command-line arguments <reference/cmdline>` or through a
+:ref:`configuration file <reference/cmdline/config>`.
+
+Common necessary configurations are:
+
+* PostgreSQL host, port, 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.
+
+  This may require creating new PostgreSQL roles, by default the only user is
+  ``postgres``, and Odoo forbids connecting as ``postgres``.
+* Custom addons path beyond the defaults, to load your own modules
+
+.. _setup/install/vcs:
+
+VCS Checkout
+============
+
+The VCS Checkout installation method is similar to
+:ref:`source-based installation <setup/install/source>` in most respect.
+
+* Instead of downloading a tarball the Odoo source code is downloaded from
+  `the repository`_ using git_
+* This simplifies the development and contributions to Odoo itself
+* This also simplifies maintaining non-module patches on top of the base Odoo
+  system
+
+The primary drawback of the VCS checkout method is that it is significantly
+larger than a :ref:`source install <setup/install/source>` as it contains
+the entire history of the Odoo project.
+
+.. _demo: https://demo.odoo.com
+.. _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: http://wkhtmltopdf.org/downloads.html
+.. _UAC: http://en.wikipedia.org/wiki/User_Account_Control
+.. _wkhtmltopdf: http://wkhtmltopdf.org
+.. _pip: https://pip.pypa.io
+.. _macports: https://www.macports.org
+.. _homebrew: http://brew.sh
+.. _Visual C++ Compiler for Python 2.7:
+    http://www.microsoft.com/en-us/download/details.aspx?id=44266
+.. _wheels: https://wheel.readthedocs.org/en/latest/
+.. _virtual environment: http://docs.python-guide.org/en/latest/dev/virtualenvs/
+.. _pywin32: http://sourceforge.net/projects/pywin32/files/pywin32/
+.. _the repository: https://github.com/odoo/odoo
+.. _git: http://git-scm.com
diff --git a/openerp/service/server.py b/openerp/service/server.py
index 43f9aadcbe7..c94d0972f75 100644
--- a/openerp/service/server.py
+++ b/openerp/service/server.py
@@ -301,7 +301,7 @@ class ThreadedServer(CommonServer):
             win32api.SetConsoleCtrlHandler(lambda sig: self.signal_handler(sig, None), 1)
 
         test_mode = config['test_enable'] or config['test_file']
-        if not stop or test_mode:
+        if test_mode or (config['xmlrpc'] and not stop):
             # some tests need the http deamon to be available...
             self.http_spawn()
 
@@ -543,12 +543,13 @@ class PreforkServer(CommonServer):
                 self.worker_kill(pid, signal.SIGKILL)
 
     def process_spawn(self):
-        while len(self.workers_http) < self.population:
-            self.worker_spawn(WorkerHTTP, self.workers_http)
+        if config['xmlrpc']:
+            while len(self.workers_http) < self.population:
+                self.worker_spawn(WorkerHTTP, self.workers_http)
+            if not self.long_polling_pid:
+                self.long_polling_spawn()
         while len(self.workers_cron) < config['max_cron_threads']:
             self.worker_spawn(WorkerCron, self.workers_cron)
-        if not self.long_polling_pid:
-            self.long_polling_spawn()
 
     def sleep(self):
         try:
diff --git a/openerp/tools/config.py b/openerp/tools/config.py
index 5f8315fea6c..d5ab9be1b81 100644
--- a/openerp/tools/config.py
+++ b/openerp/tools/config.py
@@ -73,7 +73,7 @@ def _get_default_datadir():
     return func(appname=release.product_name, appauthor=release.author)
 
 class configmanager(object):
-    def __init__(self, fname=None):
+    def __init__(self):
         # Options not exposed on the command line. Command line options will be added
         # from optparse's parser.
         self.options = {
@@ -94,7 +94,6 @@ class configmanager(object):
         self.casts = {}
 
         self.misc = {}
-        self.config_file = fname
         self.has_ssl = check_ssl()
 
         self._LOGLEVELS = dict([
@@ -378,8 +377,7 @@ class configmanager(object):
             rcfilepath = os.path.expanduser('~/.openerp_serverrc')
 
         self.rcfile = os.path.abspath(
-            self.config_file or opt.config \
-                or os.environ.get('OPENERP_SERVER') or rcfilepath)
+            opt.config or os.environ.get('OPENERP_SERVER') or rcfilepath)
         self.load()
 
         # Verify that we want to log or not, if not the output will go to stdout