.. _installation_deployment_apache:

Deployment with Apache and mod_wsgi
===================================

This documentation assumes you have Apache already installed on your system. If
you do not, install `Apache <http://httpd.apache.org>`_ 2.X for your platform
in whatever manner makes sense.

This section assumes you have read :ref:`installation_deployment`.

Installing mod_wsgi
-------------------

Once Apache is installed, we are going to install `mod_wsgi
<http://pypi.python.org/pypi/mod_wsgi>`_. First of all, we need the Apache
development package:

.. code-block:: bash

   $ sudo aptitude install apache2-dev

Then, run the following command to put ``mod_wsgi`` into your virtual
environment:

.. code-block:: bash

   (virtualenv)$ pip install mod_wsgi

To verify that the installation was successful, run the ``mod_wsgi-express``
script with the ``start-server`` command:

.. code-block:: bash

   (virtualenv)$ mod_wsgi-express start-server

Creating WSGI script
--------------------

Within the ``PubliForge`` directory of `pfinstance` user home directory
(e.g. ``/home/pfinstance/PubliForge``), create a script named
``pfinstance.wsgi`` with the following content:

.. code-block:: python

    from os import environ
    from pyramid.paster import get_app, setup_logging

    environ['VIRTUAL_ENV'] = '/usr/local/virtualenv'
    environ['HGENCODING'] = 'utf-8'
    ini_path = '/home/pfinstance/PubliForge/pfinstance.ini'
    setup_logging(ini_path)
    application = get_app(ini_path, 'main')

Configuring Apache
------------------

Configuring Default Locale
``````````````````````````
You need an UTF-8 environment for Apache. To do so, edit
``/etc/apache2/envvars`` file and uncomment the following line:

.. code-block:: guess

    ## Uncomment the following line to use the system default locale instead:
    . /etc/default/locale

Of course, your system default locale must be UTF-8 as explained in
:ref:`installation_deployment`.

Activating WSGI Module
``````````````````````
To activate the WSGI module, you need to create inside the
``/etc/apache2/mods-available`` directory the two following files.

**wsgi.conf**:

.. code-block:: guess

   <IfModule mod_wsgi.c>
       WSGIPythonHome '/usr/local/virtualenv'
       WSGIApplicationGroup %{GLOBAL}
       WSGIPassAuthorization On
   </IfModule>

**wsgi.load**:

   .. code-block:: guess

      LoadModule wsgi_module /usr/local/virtualenv/lib/python2.7/site-packages/mod_wsgi/server/mod_wsgi-py27.so

Then, enable it:

.. code-block:: bash

   $ sudo a2enmod wsgi
   $ sudo systemctl restart apache2.service

Creating the New Site
`````````````````````
Now, in ``/etc/apache2/sites-available``, create a ``pfinstance.conf`` file
with the following content:

.. code-block:: ApacheConf

    <VirtualHost *:80>
        ServerName www.pfinstance.org
        CustomLog  ${APACHE_LOG_DIR}/access_pfinstance.log combined

        KeepAlive Off

        Alias /Static/     /usr/local/virtualenv/lib/python2.7/site-packages/PubliForge-2.3.0-py2.7-linux-x86_64.egg/publiforge/Static/
        Alias /robots.txt  /usr/local/virtualenv/lib/python2.7/site-packages/PubliForge-2.3.0-py2.7-linux-x86_64.egg/publiforge/Static/robots.txt
        Alias /favicon.ico /usr/local/virtualenv/lib/python2.7/site-packages/PubliForge-2.3.0-py2.7-linux-x86_64.egg/publiforge/Static/favicon.ico
        <Directory /usr/local/virtualenv/lib/python2.7/site-packages/PubliForge-2.3.0-py2.7-linux-x86_64.egg/publiforge/Static>
          Require all granted
        </Directory>

        WSGIDaemonProcess pfinstance \
           user=pfinstance group=pfinstance \
           python-path=/usr/local/virtualenv/lib/python2.7/site-packages \
           python-eggs=/home/pfinstance/PubliForge/Cache/Tmp \
           processes=1 \
           threads=15 \
           maximum-requests=5000 \
           listen-backlog=100 \
           queue-timeout=45 \
           socket-timeout=60 \
           connect-timeout=15 \
           request-timeout=60 \
           inactivity-timeout=0 \
           deadlock-timeout=60 \
           graceful-timeout=15 \
           eviction-timeout=0 \
           shutdown-timeout=5 \
           send-buffer-size=0 \
           receive-buffer-size=0 \
           header-buffer-size=0 \
           response-buffer-size=0 \
           server-metrics=Off
        WSGIScriptAlias / /home/pfinstance/PubliForge/pfinstance.wsgi

        <Directory /home/pfinstance/PubliForge>
          WSGIProcessGroup pfinstance
          Require all granted
        </Directory>
    </VirtualHost>

    <VirtualHost *:80>
        ServerName   www.pfinstance.com
        Redirect permanent / http://www.pfinstance.org/
    </VirtualHost>

The ``Alias /Static`` block will greatly improve performance because requests
for this content (images, CSS, JavaScript, robots.txt and favicon.ico) will not
need to be proxied to `PubliForge` application and can be served
directly. Correct the path according to your environment.

Finally, activate this configuration and reload Apache:

.. code-block:: bash

    $ sudo a2ensite pfinstance.conf
    $ sudo systemctl restart apache2.service