From e288f9f927e644f38b9d9b64d2d37298293ffa61 Mon Sep 17 00:00:00 2001 From: Dave Page Date: Thu, 14 Jan 2016 15:20:53 +0000 Subject: [PATCH] Add notes on server vs. desktop deployment. --- docs/en_US/desktop-deployment.rst | 57 ++++++++++++++++++++++ docs/en_US/index.rst | 14 ++++++ docs/en_US/server-deployment.rst | 80 +++++++++++++++++++++++++++++++ 3 files changed, 151 insertions(+) create mode 100644 docs/en_US/desktop-deployment.rst create mode 100644 docs/en_US/server-deployment.rst diff --git a/docs/en_US/desktop-deployment.rst b/docs/en_US/desktop-deployment.rst new file mode 100644 index 000000000..457e7ec8b --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/en_US/index.rst b/docs/en_US/index.rst index a1e322e0e..2c3eba1fd 100644 --- a/docs/en_US/index.rst +++ b/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 *********** diff --git a/docs/en_US/server-deployment.rst b/docs/en_US/server-deployment.rst new file mode 100644 index 000000000..eba28cc51 --- /dev/null +++ b/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 + + + ServerName pgadmin.example.com + WSGIScriptAlias / "C:\Program Files\pgAdmin4\web\pgAdmin4.wsgi" + + Order deny,allow + Allow from all + + + +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 + + + ServerName pgadmin.example.com + + WSGIDaemonProcess pgadmin processes=1 + WSGIScriptAlias / /opt/pgAdmin4/web/pgAdmin4.wsgi + + + WSGIProcessGroup pgadmin + WSGIApplicationGroup %{GLOBAL} + Order deny,allow + Allow from all + + \ No newline at end of file