Proxy upgrade configuration

Instructions for configuring EventQ to run behind TeamForge's web server.

To provide a seamless experience for users, the EventQ HTTP(S) service is proxied through TeamForge by default as of TeamForge version 8.1, meaning end users access EventQ using the TeamForge hostname and port. This proxy configuration must be set up manually for those upgrading from EventQ versions 1.4.1 or earlier. This document provides step-by-step instructions for configuring the proxy. Failure to configure the proxy will interfere with functionality and is therefore a required part of the upgrade process.

Assumptions - for purposes of this guide, assume the following:
  • An existing TeamForge host using SSL named ctf.example.com
  • An existing EventQ host using SSL named eventq.example.com
  • All hosts have been upgraded to the target version (e.g. 17.4), see Upgrade EventQ
  • All hosts are running SSL services on port 443
  • Firewall permits traffic on port 443 between TeamForge and EventQ hosts
  • Hosts have existing certificate files
  • Certificate files are signed by "legitimate" CAs
  • Hosts are otherwise using their 'standard' production installs (e.g., EventQ installs nginx configs in /opt/collabnet/nginx/conf/collabnet-nginx.conf, TeamForge uses /opt/collabnet, etc.)
  • The user has sudo or equivalent access on both TeamForge and EventQ hosts

Prepare TeamForge (without certificate validation)

  1. Configure TeamForge site-options. Comment out the ORC_SSL_CA_CERT_FILE token in the TeamForge host's site-options.conf file if you are not enabling certificate validation between EventQ and TeamForge.

    Supply the following values to the TeamForge host's site-options.conf (whichever file your host is using as the source of its site options):

    ORCHESTRATE_ENABLED=true
    ORC_PROXIED_PATH=/orc
    ORC_PORT=443
    ORC_HOSTNAME=eventq.example.com
    ORC_PROTOCOL=https
    #ORC_SSL_CA_CERT_FILE
  2. Re-create TeamForge runtime

Prepare TeamForge (with certificate validation)

  1. Locate or create CA certificate files
    If the TeamForge host does not already have a root CA bundle which can validate EventQ's certificate, create or download such a file. Options include:
    • For certificates that are signed by a common CA, this may already be installed by the yum package 'ca-certificates';
    • Obtain from a common source, such as https://raw.githubusercontent.com/bagder/ca-bundle/master/ca-bundle.crt;
    • If the certificate is self-signed, this file is likely the certificate itself;
    • Otherwise, this file can be created by concatenating the certificates of the CA that signed EventQ's certificate, along with the certificates of all intermediary signing CAs.
    See http://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslproxycacertificatefile for more info on precisely what the root CA certificate file is expected to contain.

    If the CA bundle file is not already available/accessible on the TeamForge host, copy it to a suitable location on the TeamForge host, e.g., /var/ops/ssl/ca-bundle.crt.

  2. Test the CA certicate file

    The following is a simple command line sanity check, run from the TeamForge server.

    [root@ctf.example.com]$ echo |openssl s_client -connect orc.example.com:443 -CAfile /var/ops/ssl/ca-bundle.crt > /dev/null depth=2 /C=US/O=GeoTrust Inc./CN=GeoTrust Global CA verify return:1 depth=1 /C=US/O=GeoTrust, Inc./CN=RapidSSL CA verify return:1 depth=0 /serialNumber=sXupsaptbZJc4PUuawYNAYey2fPMfuXA/OU=GT99362291/OU=See www.rapidssl.com/resources/cps (c)14/OU=Domain Control Validated - RapidSSL(R)/CN=*.example.com verify return:1 DONE

    You are looking for the presence of verify return:1 in each step of the certificate validation chain. If the certificate was unable to be validated you may instead see:

    [root@ctf.example.com]$ echo |openssl s_client -connect orc.example.com:443 -CAfile /var/ops/ssl/ca-bundle.crt > /dev/null verify error:num=20:unable to get local issuer certificate verify return:0

  3. Configure TeamForge site-options

    Supply the following values to the TeamForge host's site-options.conf (whichever file your host is using as the source of its site options):

    ORCHESTRATE_ENABLED=true
    ORC_PROXIED_PATH=/orc
    ORC_PORT=443
    ORC_HOSTNAME=eventq.example.com
    ORC_PROTOCOL=https
    ORC_SSL_CA_CERT_FILE=/var/ops/ssl/ca-bundle.crt
    
  4. Deploy TeamForge services

Prepare EventQ

  1. Edit EventQ's nginx configuration

    Edit /opt/collabnet/nginx/conf/collabnet-nginx.conf to have the following (omitting the non-relevant bits):

     ...
      server {
        listen 443;
        server_name eventq.example.com;
        ...
        # Redirect root to /orc
        location / {
          rewrite ^ https://eventq.example.com:443/orc$request_uri? permanent;
        }
      }
      ... 
      # This provides a HTTP->HTTPS redirect for eventq
      server {
        listen 80;
        server_name eventq.example.com;
        ...
        # redirect 80 to 443
        location / {
          rewrite ^ https://eventq.example.com:443$request_uri? permanent;
        }
      }
      passenger_pre_start https://eventq.example.com:80/orc/;
      passenger_pre_start https://eventq.example.com:443/orc/;
      ...
    
  2. Test nginx configuration

    Test the edited configuration before restarting. The example below assumes a user eventq with sudo access:

    [eventq@eventq.example.com]# sudo /opt/collabnet/nginx/sbin/nginx -c /opt/collabnet/nginx/conf/collabnet-nginx.conf -t nginx: the configuration file /opt/collabnet/nginx/conf/collabnet-nginx.conf syntax is ok nginx: configuration file /opt/collabnet/nginx/conf/collabnet-nginx.conf test is successful

  3. Edit EventQ's defaults.yml

    Edit EventQ's /opt/collabnet/eventq/config/defaults.yml to ensure that the teamforge.production.server and teamforge.production.iaf.orc_url have the correct proxied URLs (omitting irrelevant bits):

     ...
    teamforge:
      production:
        server: https://ctf.example.com
        iaf:
          ...
          orc_url: https://ctf.example.com/orc
    ...
    
  4. Restart nginx

    [eventq@eventq.example.com]#sudo service collabnet-nginx restart

Update TeamForge's IAF settings

  1. Update the existing IAF and Site-wide linked app

    This assumes that the EventQ service runs under the user eventq on the eventq host, and can bring up a rails console (hence use of sudo, and the console invocation). Use that user to bring up a console, and manually call CtfConfigurer.new.edit_iaf_application:

    [eventq@eventq.example.com]#cd /opt/collabnet/eventq sudo su - eventq bundle exec rails c production rb(main):003:0> CtfConfigurer.new.edit_iaf_application => {:set_integrated_application_icon_response=>nil}

  2. Update existing Site-wide linked app

    This step requires login to the TeamForge web application

    1. In TeamForge, as a site-admin navigate to: Admin > Integrations > Site-wide Linked Applications.
    2. Click the EventQ application to edit.
    3. Edit the URL to the one being proxied

      e.g., https://ctf.example.com/orc/users/auth/teamforge/callback

    4. Save edits