← Back to team overview

sloecode-dev team mailing list archive

documentation for reverse proxy scenario

 

As requested, I've written up a bit of documentation on how to do the
reverse proxy to front a Sloecode instance running on a "private" port.
I hope I didn't mess up anything when extracting the stuff from my
Fabric+Cuisine deployment script, and I've tried to add some description
for it as well.

Any feedback (or use otherwise) welcome.

Guy

PS: Might make sense to place instructions within a doc/ directory or so
in the Sloecode code base.



-- 
Guy K. Kloss
School of Computing + Mathematical Sciences
Auckland University of Technology
Private Bag 92006, Auckland 1142
phone: +64 9 921 9999 ext. 5032
eMail: Guy.Kloss@xxxxxxxxx
======================
Reverse Proxy Scenario
======================

In certain cases the "vanilla" install option (e. g. from the PPA
repository used as an Apache WSGI web application) may not be
sufficient.  One such case is if an (Apache) web server is to host
multiple web applications, which should otherwise be "neatly"
separated in terms of configuration, executing users/privileges,
(error) logging, etc.  This may also be desirable, if a specific
server is equipped with a trusted SSL certificate, and is to host the
different services without the need to purchase more certificates or
wild-card certificates.  Although, this documentation does not address
the issue of SSL configuration, only unencrypted HTTP on a final
destination port 80 is assumed.

The documentation in this scenario assumes the delivery of the
Sloecode instance through Apache's ``mod_wsgi`` (as a WSGI web
application), while "peacefully" co-existing with other web
applications to be served by Apache.  To make this work through the
limitations of ``mod_wsgi`` we are assuming, that each web application
can be uniquely identified from the outside through the URL path of
the domain, e. g. http://example.org/sc/ for Sloecode,
http://example.org/other for some other web application.  Apache is
used in a three-fold way for this:

 * To host the Sloecode WSGI web application

 * To host the "other" web application

 * To provide a reverse proxy, that dispatches requests depending on
   their URL to the correct hosted application(s).


Installation
------------

The install mainly follows the procedures as outlined from an install
through the developers' or stable PPA as outlined in the main install
documentation.  (All these actions described are to be executed on the
server.)  Following are the major steps to install Sloecode using the
reverse proxy scenario: Install Sloecode, configure WSGI, configure
Sloecode, and install/configure the reverse proxy.  Lastly, the
"other" application needs to be installed/configured and integrated
into the reverse proxy.  This documentation will only gloss briefly
over it, as we just assume that you know how that works to deploy
it in some proper way.


Install Sloecode
^^^^^^^^^^^^^^^^

This is easy, just install the ``sloecode`` package and configure as
normal.


Configure the Apache WSGI part for Sloecode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1) Enable the site in your Apache 2 configuration:
   
   .. code-block:: sh

      > a2ensite sloecode

2) Choose a new/vacant port to serve the Sloecode instance under
   (internally): This would usually be a restricted port, e. g. 8001.

   Now configure the Apache site accordingly, by altering at its top
   what port the ``VirtualHost`` is listening on:

   .. code-block:: apacheconf

      Listen 8001
      NameVirtualHost *:8001
      <VirtualHost *:8001>

   At this point, you may also alter the configurations for
   ``ServerName``, ``ServerAdmin``, as well as add separate logs for
   ``ErrorLog`` and ``CustomLog`` (to keep logging messages web
   application specific):

   .. code-block:: apacheconf

      ErrorLog /var/log/apache2/sloecode.error.log
      CustomLog /var/log/apache2/sloecode.log common

3) To keep the reverse proxy as simple and lean as possible, it is
   quite helpful to already serve Sloecode under a path (within the
   URL) that can be easily re-mapped **without** having to rewrite all
   HTML and CSS content.  For this purpose we're serving Sloecode with
   the URL prefix ``/sc``.  To do this, again Apache's site
   configuration needs to be altered.  Change in the ``sloecode`` site
   the ``WSGIScriptAlias`` line in the following manner to serve under
   the above given prefix:

   .. code-block:: apacheconf

      WSGIScriptAlias /sc /usr/share/sloecode/wsgi/sloecode.wsgi

4) Restart the Apache process to enable the new site:

   .. code-block:: sh

      > service apache2 restart

Now the site *should* be properly responding already to requests to
http://example.org:8001/sc.  However, it is better to at least finish
the next configuration section before trying anything, otherwise
errors are hard to track and resolve.


Configure Sloecode
^^^^^^^^^^^^^^^^^^

Now the Apache site for hosting Sloecode under the "private" port
(e. g. 8001) should be done.  Next we will need to re-configure
Sloecode itself.

1) Adjust the settings in the Sloecode configuration.  For the purpose
   of this documentation this is limited to editing
   ``/etc/sloecode/production.ini``.

   - Adjust the settings in the ``[DEFAULT]`` section, particularly
     change the ``http_server_port`` (to 8001).

   - Adjust the ``xmlrpc_auth_endpoint`` setting in the
     ``[smartserver]`` section by inserting the URL path prefix
     (``/sc``)

     .. code-block:: ini

        xmlrpc_auth_endpoint = http://localhost:%(http_server_port)s/sc/xmlrpc

2) It is also a good idea to generate/configure the ``production.ini``
   with a new 32 byte random secret at this time.  This is changed in
   the ``[app:main]`` section in the ``beaker.session.secret``
   setting.  Be safe, and just use some non-trivial, random sequence
   for this!

3) If you haven't done so, yet, run the setup script for priming the
   database for Sloecode.  **If you do this with an already existing
   database, you're going to wipe all content!** If you've got a file
   ``//srv/sloecode/sloecode``, you've got a database already.

   .. code-block:: sh

      > paster setup-app /etc/sloecode/production.ini

4) Start your Sloecode smart server

   .. code-block:: sh

      > service sloecode start


Install/configure your reverse proxy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The reverse proxy will redirect requests coming in on the standard
HTTP port (80) to the internally hosted instances running on a private
port.  This way requests coming in on http://example.org/sc/ will be
redirected to http://example.org:8001/sc/ and
http://example.org/other/ to http://example.org:8002/other/.

As we've tried to make sure that no URL path collisions are arising
through our scenario, and everything is "nicely" prefixed in the URL
path, this setup is not as painful as it may seem.  Particularly, this
way we do not have to worry about content rewriting, which would take
another overhead on the web server, which does not increase
productivity.

1) Install the required reverse proxy packages through the package
   manager: ``libapache2-mod-proxy-html`` and ``libapache2-mod-rpaf``.

2) Enable the new and required Apache modules.

   .. code-block:: sh

      > a2enmod proxy
      > a2enmod proxy_http
      > a2enmod headers

3) Configure a new Apache site
   ``/etc/apache2/sites-available/reverse_proxy`` for the default port
   80 which handles the reverse proxy.  The following configuration
   can be used as a skeleton (the "other" web application is hosted in
   a similar fashion as Sloecode, but under port 8002):

   .. code-block:: apacheconf

      <VirtualHost *:80>
          ServerAdmin your.mail@xxxxxxxxxxx
          ServerName example.org
          
          # Configure the Sloecode instance.
          ProxyPass       /sc/  http://localhost:8001/sc/
          ProxyHTMLURLMap http://example.org:8001 /
          <Location /sc/>
              RequestHeader unset Accept-Encoding
              ProxyPassReverseCookiePath / /sc/
          </Location>
          
          # Configure the "other site".
          ProxyPass       /other/  http://localhost:8002/other/
          ProxyHTMLURLMap http://putake.aut.ac.nz:8002 /
          <Location /other/>
              RequestHeader unset Accept-Encoding
              ProxyPassReverse /other/
          </Location>
      
          ## General configurations for this site.
          # This directive allows us to have apache2's default start page
          # in /sc/, but still have / go to the right place.
          RedirectMatch ^/$ /sc/
      
          Alias /robots.txt /var/www/robots.txt
          Alias /favicon.ico /usr/share/pyshared/sloecode/public/sloe.ico
          
          ErrorLog /var/log/apache2/reverse_proxy.error.log
          CustomLog /var/log/apache2/reverse_proxy.log common
      </VirtualHost>

   .. note::

      Depending on the "other" application, further configuration of
      the reverse proxy may be required.
      http://www.apachetutor.org/admin/reverseproxies may give some
      further help on getting started with "A Reverse Proxy Scenario".
      It may also make sense to allow access to the "private port"
      hosted instances only from ``localhost``, but this is further
      tweaking, which is not discussed here in more detail.

4) Enable the new site for the default port 80.

   .. code-block:: sh

      > a2ensite reverse_proxy

5) Restart the Apache process to enable the new site:

   .. code-block:: sh

      > service apache2 restart


Configure "other" web application
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Obviously, the "other" web application needs to be installed and
configured to be hosted on http://localhost:8002/other/ to make things
work.