Configuring a web proxy

Authors:Michael JasonSmith; Fabien Hespul
Contact:Michael JasonSmith <mpj17@onlinegroups.net>
Date:2015-02-12
Organization:GroupServer.org
Copyright:This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.net.

Introduction

While GroupServer can run as a stand-alone web-server, it is highly recommended that a proxy is used when making the site available to the public to provide the following services:

  • To mediate between the low level HTTP port (port 80) and the high-port that Zope runs on (normally port 8080).
  • To rewrite the URL to include a skin directive.
  • To rewrite the URL to support virtual hosting.
  • To provide caching.
  • To provide a secure connection.

In this document we explain how to add a virtual host to either Apache or nginx, and how to change the reported port in GroupServer. We then explain how to change the skin, before we outline how to set up secure connections.

Note:You will need to be the root user to carry out most of these tasks. Commands that need to be run as root will be shown with # prompt, rather than a $.

Add a virtual host

If you have a new domain [1] that you want to use with your GroupServer installation first you must update the GroupServer configuration and then add a virtual host to Apache or Add a virtual host to nginx.

Update the GroupServer configuration

If you used a host such as gstest to try out GroupServer then you will need to update the configuration for GroupServer itself.

  1. Visit the ZMI for your site. Log in if necessary.
  2. Visit the folder /groupserver/Content/initial_site/.
  3. Open the DivisionConfiguration.
  4. Set the canonicalHost to the domain for your new site.
  5. Set the canonicalPort to 80.
  6. Click the Save Changes button.

Add a virtual host to Apache

To add a virtual host to Apache carry out the following steps.

  1. Ensure the rewrite, proxy, and proxy_httpd modules are enabled in Apache:

    # a2enmod rewrite proxy proxy_http
    # service apache2 restart
    
  2. Open /etc/apache2/sites-available/groupserver in a text-editor.

  3. Add the following to the file

    <VirtualHost *:80>
      ServerAdmin support@example.com
      ServerName groups.example.com
    
      RewriteEngine on
      RewriteRule ^/(.*) http://localhost:8080/groupserver/Content/initial_site/VirtualHostBase/http/%{HTTP_HOST}:80/VirtualHostRoot/$1 [L,P]
    
      ProxyVia On
    
      ErrorLog ${APACHE_LOG_DIR}/error.log
    
      # Possible values include: debug, info, notice, warn, error, crit,
      # alert, emerg.
      LogLevel info
    
      CustomLog ${APACHE_LOG_DIR}/access.log combined
    </VirtualHost>
    
    • Change the address for the site from groups.example.com to that of you new virtual host.
    • Change the email address for ServerAdmin from support@example.com to the value of the support_email in the config.cfg file in the GroupServer directory.
  4. Link the configuration for your host:

    # cd /etc/apache2/sites-enabled/
    # ln -s ../groupserver 100-groupserver
    
  5. Restart Apache:

    # service apache2 restart
    

Add a virtual host to nginx

Open /etc/nginx/sites-avaliable/groupserver in a text-editor.

  1. Add the following to the file

    upstream gs {
      server localhost:8080;
    }
    
    server {
      listen 80;
      server_name groups.example.com;
    
      location / {
        rewrite /(.*) /VirtualHostBase/http/$host:80/groupserver/Content/initial_site/VirtualHostRoot/$1 break;
        proxy_pass http://gs/;
        include proxy_params;
      }
    }
    
    server {
      listen 80;
      server_name zmi.groups.example.com;
    
      location / {
        rewrite /(.*) /VirtualHostBase/http/$host:80/VirtualHostRoot/$1 break;
        proxy_pass http://gs/;
        include proxy_params;
      }
    }
    
    • Change the server_name from groups.example.com to that of you new virtual host.
    • Make a similar change to the second server, keeping the zmi. at the start.
  2. Link the configuration for your host:

    # cd /etc/nginx/sites-enabled/
    # ln -s 100-groupserver ../groupserver
    
  3. Reload the nginx configuration:

    # service nginx reload
    

Change the reported port

Notifications from GroupServer (such as the Welcome email to a new group member) normally contain links back to the site. These links will reference the port that was used when GroupServer was built (8080) rather than the new HTTP or HTTPS port provided by the proxy. To change the port that GroupServer says it is using carry out the following tasks.

  1. Connect to the ZMI for your site.
  2. Visit the folder for your site, at groupserver/Content/initial_site.
  3. Open the DivisionConfiguration object.
  4. Select the check-box next to the canonicalPort line.
  5. Click the Delete button. The canonicalPort value will be deleted.
Note:In the unlikely case that a non-standard port is used, change the value of the canonicalPort and click the Save changes button, rather than deleting the property.

Change the skin

One of the advantages of adding a proxy is it allows the skin to be easily changed. GroupServer ships with two skins: green and blue. To change the skin you must alter the rewrite rule. In the case of nginx the rewrite rule will look like the following

rewrite /(.*) /++skin++gs_blue/VirtualHostBase/http/$host:80/groupserver/Content/initial_site/VirtualHostRoot/$1 break;

In the case of Apache the rewrite rule would look like the following

RewriteRule ^/(.*) http://localhost:8080/++skin++gs_green/groupserver/Content/initial_site/VirtualHostBase/http/%{HTTP_HOST}:80/VirtualHostRoot/$1 [L,P]

Secure connections: TLS, SSL, and HTTPS

Establishing a secure connection is done by the proxy rather than GroupServer itself. The proxy should still listen to port 80 (HTTP) and make a permanent redirect to the secure site by returning a 301 response. In nginx the rule would look like the following:

server {
  listen 80;
  server_name groups.example.com;

  return 301 https://$server_name$request_uri;
}

The proxy will also listen to the secure port and perform a rewrite to your GroupServer site. This is similar to the rewrite when you add a virtual host, but

  • There is configuration for the SSL certificates,
  • The port is 443, rather than 80, and
  • The protocol is https rather than http.
server {
  listen 443;
  server_name groups.example.com;

  ssl on;
  ssl_certificate /etc/nginx/ssl/groups.example.com.crt;
  ssl_certificate_key /etc/nginx/ssl/groups.example.com.key;

  location / {
    rewrite /(.*) /VirtualHostBase/https/$host:443/groupserver/Content/initial_site/VirtualHostRoot/$1 break;
    proxy_pass http://gs/;
    include proxy_params;
  }
}

You can change the skin in the rewrite rule, just like before.

[1]Acquiring and configuring a new domain is out of the scope for this documentation. However, you want the A-record for your new domain to point to the IP of your GroupServer site, and the MX-record to also point at your new site.
[2]Leave the port set to 8080.