Proxy upgrade configuration

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

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)

3. 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.

4. 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

5. 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
   

6. Re-create TeamForge runtime

Prepare Orchestrate

7. 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/;
     ...
   

8. 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

9. 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
   ...
   

10. Restart nginx

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

Update TeamForge's IAF settings

11. 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}

12. 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