Proxy upgrade configuration

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

To provide a seamless experience for users, the Orchestrate HTTP(S) service is proxied through TeamForge by default as of version 8.1, meaning end users access Orchestrate using the TeamForge hostname and port. This proxy configuration must be set up manually for those upgrading from Orchestrate versions 1.4.1 or before. This document provides a step-by-step guide 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 Orchestrate host using SSL named orc.example.com
  • All hosts have been upgraded to the target version (e.g. 8.1), see Upgrading TeamForge Orchestrate
  • All hosts are running SSL services on port 443
  • Firewall permits traffic on port 443 between TeamForge and Orchestrate hosts
  • Hosts have existing certificate files
  • Certificate files are signed by "legitimate" CAs
  • Hosts are otherwise using their 'standard' production installs (e.g., Orchestrate 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 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 Orchestrate 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=orc.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 Orchestrate'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 Orchestrate'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=orc.example.com
    ORC_PROTOCOL=https
    ORC_SSL_CA_CERT_FILE=/var/ops/ssl/ca-bundle.crt
    
  4. Re-create TeamForge runtime

Prepare Orchestrate

  1. Edit Orchestrate'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 orc.example.com;
        ...
        # Redirect root to /orc
        location / {
          rewrite ^ https://orc.example.com:443/orc$request_uri? permanent;
        }
      }
      ... 
      # This provides a HTTP->HTTPS redirect for orchestrate
      server {
        listen 80;
        server_name orc.example.com;
        ...
        # redirect 80 to 443
        location / {
          rewrite ^ https://orc.example.com:443$request_uri? permanent;
        }
      }
      passenger_pre_start https://orc.example.com:80/orc/;
      passenger_pre_start https://orc.example.com:443/orc/;
      ...
    
  2. Test nginx configuration

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

    [orchestrate@orc.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 Orchestrate's defaults.yml

    Edit Orc's /opt/collabnet/orchestrate/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

    [orchestrate@orc.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 Orc service runs under the user orchestrate on the orchestrate 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:

    [orchestrate@orc.example.com]#cd /opt/collabnet/orchestrate sudo su - orchestrate 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 Orchestrate 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