Add notes on server vs. desktop deployment.

docs/en_US/desktop-deployment.rst

@@ -0,0 +1,57 @@
+Desktop Deployment
+==================
+
+pgAdmin may be deployed as a desktop application by configuring the application
+to run in desktop mode and then utilising the desktop runtime to host and
+display the program on a supported Windows, Mac OS X or Linux installation.
+
+**Note: Pre-compiled and configured installation packages are available for
+a number of platforms. These packages should be used by end-users whereever
+possible - the following information is useful for the maintainers of those
+packages and users interested in understanding how pgAdmin works.**
+
+Configuration
+*************
+
+In order to configure pgAdmin to run in desktop mode, it is first necessary to
+configure the Python code to run in single-user mode, and then to configure the
+runtime to find and execute the code.
+
+Python
+------
+
+In order to configure the Python code, follow these steps:
+
+1. Ensure that any existing configuration database (``pgadmin4.db``) is moved 
+   out of the way in the ``web/`` directory containing the pgAdmin Python code.
+
+2. Create a ``config_local.py`` file alongside the existing ``config.py`` file.
+
+3. Edit ``config_local.py`` and add the following setting:
+
+   .. code-block:: python
+
+       SERVER_MODE = False
+    
+4. Run the following command to create the configuration database:
+
+   .. code-block:: bash
+
+       $ python setup.py
+    
+Runtime
+-------
+
+When executed, the runtime will automatically try to execute the pgAdmin Python
+application. If execution fails, it will prompt you to adjust the Python Path
+to include the directories containing the pgAdmin code as well as any additional
+Python dependencies. You can enter a list of paths by separating them with a
+semi-colon character, for example:
+
+.. code-block:: bash
+
+     /Users/dpage/.virtualenvs/pgadmin4/lib/python2.7/site-packages/;/Users/dpage/python-libs/
+    
+The configuration settings are stored using the QSettings class in Qt, which 
+will use an INI file on Unix systems, a plist file on Mac OS X, and the registry
+on Windows. The Python Path setting is stored in the ``PythonPath`` key.

docs/en_US/index.rst

@@ -60,6 +60,20 @@ individual features.
    debugger
    query-tool
 
+**********
+Deployment
+**********
+
+pgAdmin is primarily written as a web application and may be deployed as a 
+multi-user application on a web server. It also includes a simple runtime
+that may be used to host the program as a desktop application.
+
+.. toctree::
+   :maxdepth: 1
+   
+   desktop-deployment
+   server-deployment
+
 ***********
 Development
 ***********

docs/en_US/server-deployment.rst

@@ -0,0 +1,80 @@
+Server Deployment
+=================
+
+pgAdmin may be deployed as a web application by configuring the app to run in
+server mode and then deploying it either behind a webserver running as a reverse
+proxy, or using the WSGI interface.
+
+The following instructions demonstrate how pgAdmin may be run as a WSGI 
+application under ``Apache HTTP``, using ``mod_wsgi``.
+
+Requirements
+------------
+
+**Important**: Some components of pgAdmin require the ability to maintain affinity
+between client sessions and a specific database connection (for example, the 
+Query Tool in which the user might run a BEGIN command followed by a number of
+DML SQL statements, and then a COMMIT). pgAdmin has been designed with built-in
+connection management to handle this, however it requires that only a single
+Python process is used because it is not easily possible to maintain affinity
+between a client session and one of multiple WSGI worker processes.
+
+On Windows systems, the Apache HTTP server uses a single process, multi-threaded
+architecture. WSGI applications run in ``embedded`` mode, which means that only
+a single process will be present on this platform in all cases.
+
+On Unix systems, the Apache HTTP server typically uses a multi-process, single
+threaded architecture (this is dependent on the ``MPM`` that is chosen at 
+compile time). If ``embedded`` mode is chosen for the WSGI application, then
+there will be one Python environment for each Apache process, each with it's own
+connection manager which will lead to loss of connection affinity. Therefore
+one should use ``mod_wsgi``'s ``daemon`` mode, configured to use a single
+process. This will launch a single instance of the WSGI application which is 
+utilised by all the Apache worker processes.
+
+Whilst it is true that this is a potential performance bottleneck, in reality
+pgAdmin is not a web application that's ever likely to see heavy traffic 
+unlike a busy website, so in practice should not be an issue.
+
+Future versions of pgAdmin may introduce a shared connection manager process to
+overcome this limitation, however that is a significant amount of work for 
+little practical gain.
+
+Apache HTTPD Configuration (Windows)
+------------------------------------
+
+Once Apache HTTP has been configured to support ``mod_wsgi``, the pgAdmin
+application may be configured similarly to the example below:
+
+.. code-block:: apache
+
+    <VirtualHost *>
+        ServerName pgadmin.example.com
+        WSGIScriptAlias / "C:\Program Files\pgAdmin4\web\pgAdmin4.wsgi"
+        <Directory "C:\Program Files\pgAdmin4\web">
+                Order deny,allow
+                Allow from all
+        </Directory>
+    </VirtualHost>
+    
+Apache HTTPD Configuration (Linux/Unix)
+---------------------------------------
+
+Once Apache HTTP has been configured to support ``mod_wsgi``, the pgAdmin
+application may be configured similarly to the example below:
+
+.. code-block:: apache
+
+    <VirtualHost *>
+        ServerName pgadmin.example.com
+
+        WSGIDaemonProcess pgadmin processes=1
+        WSGIScriptAlias / /opt/pgAdmin4/web/pgAdmin4.wsgi
+
+        <Directory /opt/pgAdmin4/web>
+            WSGIProcessGroup pgadmin
+            WSGIApplicationGroup %{GLOBAL}
+            Order deny,allow
+            Allow from all
+        </Directory>
+    </VirtualHost>