Deploy Apache as web front-end for gluster-swift

Swift can alternatively be configured to work as a request processor of
Apache server. This alternative deployment scenario uses mod_wsgi of
Apache to forward requests to the swift wsgi application and middleware.

'client' <---> 'Apache2+mod_wsgi' <---> 'middleware' <---> 'core swift'

Change-Id: If396dcbdf651af0dce55b951cd2eaadc6783384f
Signed-off-by: Prashanth Pai <ppai@redhat.com>
Reviewed-on: http://review.gluster.org/6116
Reviewed-by: Luis Pabon <lpabon@redhat.com>
Tested-by: Luis Pabon <lpabon@redhat.com>

1 files changed, 180 insertions, 0 deletions

diff --git a/doc/markdown/apache-deploy.md b/doc/markdown/apache-deploy.md
new file mode 100644
index 0000000..3da2192
--- /dev/null
+++ b/doc/markdown/apache-deploy.md
@@ -0,0 +1,180 @@
+## Deploying Apache as front end for Openstack Swift in Fedora/RHEL
+
+NOTE: This guide is for manual deployment. A shell script to automate the following
+is present in extras/apache-deploy.
+
+### Architecture
+Swift can be configured to work both using an integral web front-end and
+using a full-fledged Web Server such as the Apache2 (HTTPD) web server. The
+integral web front-end is a wsgi mini "Web Server" which opens up its own
+socket and serves http requests directly. The incoming requests accepted
+by the integral web front-end are then forwarded to a wsgi application
+(the core swift) for further handling, possibly via wsgi middleware
+sub-components.
+
+    client<-->'integral web front-end'<-->middleware<-->'core swift'
+
+To gain full advantage of Apache2, Swift can alternatively be configured to
+work as a request processor of the Apache2 server. This alternative deployment
+scenario uses mod_wsgi of Apache2 to forward requests to the swift wsgi
+application and middleware.
+
+    client<-->'Apache2 with mod_wsgi'<-->middleware<-->'core swift'
+
+The integral web front-end offers simplicity and requires minimal config.
+It is also the web front-end most commonly used with Swift. Additionally, the
+integral web front-end includes support for receiving chunked transfer
+encoding from a client, presently not supported by Apache2 in the operation
+mode described here.
+
+### Steps
+
+Installing Apache with mod_wsgi module:
+
+    yum install httpd mod_wsgi
+
+Create a directory for Apache wsgi files:
+
+    mkdir /var/www/swift
+
+Create a wsgi file for each service under /var/www/swift
+
+#### /var/www/swift/proxy-server.wsgi
+    from swift.common.wsgi import init_request_processor
+    application, conf, logger, log_name = \
+        init_request_processor('/etc/swift/proxy-server.conf','proxy-server')
+
+#### /var/www/swift/account-server.wsgi
+    from swift.common.wsgi import init_request_processor
+    application, conf, logger, log_name = \
+        init_request_processor('/etc/swift/account-server.conf','account-server')
+
+#### /var/www/swift/container-server.wsgi
+    from swift.common.wsgi import init_request_processor
+    application, conf, logger, log_name = \
+        init_request_processor('/etc/swift/container-server.conf','container-server')
+
+#### /var/www/swift/object-server.wsgi
+    from swift.common.wsgi import init_request_processor
+    application, conf, logger, log_name = \
+        init_request_processor('/etc/swift/object-server.conf','object-server')
+
+
+Create */etc/httpd/conf.d/swift_wsgi.conf* configuration file that will define
+port and Virtual Host per each local service.
+
+    WSGISocketPrefix /var/run/wsgi
+    
+    #Proxy Service
+    Listen 8080
+    <VirtualHost *:8080>
+        ServerName proxy-server
+        LimitRequestBody 5368709122
+        WSGIDaemonProcess proxy-server processes=5 threads=1 user=swift
+        WSGIProcessGroup proxy-server
+        WSGIScriptAlias / /var/www/swift/proxy-server.wsgi
+        LimitRequestFields 200
+        ErrorLog /var/log/httpd/proxy-server.log
+        LogLevel debug
+        CustomLog /var/log/httpd/proxy.log combined
+    </VirtualHost>
+    
+    #Object Service
+    Listen 6010
+    <VirtualHost *:6010>
+        ServerName object-server
+        WSGIDaemonProcess object-server processes=5 threads=1 user=swift
+        WSGIProcessGroup object-server
+        WSGIScriptAlias / /var/www/swift/object-server.wsgi
+        LimitRequestFields 200
+        ErrorLog /var/log/httpd/object-server.log
+        LogLevel debug
+        CustomLog /var/log/httpd/access.log combined
+    </VirtualHost>
+    
+    #Container Service
+    Listen 6011
+    <VirtualHost *:6011>
+        ServerName container-server
+        WSGIDaemonProcess container-server processes=5 threads=1 user=swift
+        WSGIProcessGroup container-server
+        WSGIScriptAlias / /var/www/swift/container-server.wsgi
+        LimitRequestFields 200
+        ErrorLog /var/log/httpd/container-server.log
+        LogLevel debug
+        CustomLog /var/log/httpd/access.log combined
+    </VirtualHost>
+    
+    #Account Service
+    Listen 6012
+    <VirtualHost *:6012>
+        ServerName account-server
+        WSGIDaemonProcess account-server processes=5 threads=1 user=swift
+        WSGIProcessGroup account-server
+        WSGIScriptAlias / /var/www/swift/account-server.wsgi
+        LimitRequestFields 200
+        ErrorLog /var/log/httpd/account-server.log
+        LogLevel debug
+        CustomLog /var/log/httpd/access.log combined
+    </VirtualHost>
+
+(Re)Start Apache server:
+
+    service httpd stop
+    service httpd start
+
+### Troubleshooting
+
+* Make sure you have set SElinux to Permissive or Disabled by editing
+  */etc/sysconfig/selinux*. You will need to reboot your system for the
+  changed value to take effect. On restart, you can confirm this by running:
+
+        getenforce
+
+* Make sure conf files in /etc/swift are accessible by swift user:
+
+        chown swift:swift /etc/swift/*
+
+* Make sure the directory */var/lib/swift* exists should you see the following
+  error in /var/log/httpd/error_log
+
+        [Fri Oct 20 02:05:25.617290 2013] [:alert] [pid 3491] (2)No such file or
+        directory: mod_wsgi (pid=3491): Unable to change working directory to
+        '/var/lib/swift'
+
+* Make sure the port numbers in */etc/httpd/conf.d/swift_wsgi.conf* and
+  */etc/swift/*conf* files are same.
+
+* For errors in logs like the following:
+
+        13)Permission denied: mod_wsgi (pid=26962): Unable to connect to WSGI
+        daemon process '<process-name>' on '/etc/httpd/logs/wsgi.26957.0.1.sock'
+        after multiple attempts.
+
+  Refer: https://code.google.com/p/modwsgi/wiki/ConfigurationIssues#Location_Of_UNIX_Sockets
+
+* If your swift deployment uses some authentication mechanism that uses
+  HTTP_AUTHORIZATION variable, you need to turn on WSGIPassAuthorization as
+  described here:
+
+  https://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization
+
+#### Issue with gluster-swift
+Unlike vanilla swift that runs as *swift* user, gluster-swift runs all four
+swift servers as *root* user.
+
+But mod_wsgi does not allow invoking wsgi applications as root:
+https://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIDaemonProcess
+
+A workaround is to mount gluster volume as root beforehand:
+
+    mount -t glusterfs localhost:myvolume /mnt/gluster-object/myvolume
+
+
+### More information
+
+* There is a Ubuntu specific guide to deploy Apache with Openstack Swift here:
+  http://docs.openstack.org/developer/swift/apache_deployment_guide.html
+
+* Example apache configuration from swift source can be found here:
+  https://github.com/openstack/swift/tree/master/examples