Installation walk-through

Installation instructions for TeamForge Orchestrate

This guide is a step-by-step walk-through of the TeamForge Orchestrate installation process. We recommend reading this entire document before starting the installation process; the installer asks several questions and it is beneficial to have the answers handy. Where applicable, default answers are denoted in square brackets.

As suggested in Installation requirements, prepare your target server(s) prior to installation. We recommend these preparations on the target host(s):

prepare SSH users and passwords/keys
ensure SSH users have sudo "root" privileges
if using SSH keys, locate your SSH private key on the primary installation server (App server) (e.g., /home/user/.ssh/id_rsa).
locate your SSL key and cert files on the primary installation server (App server)

Configure proxy for web access

Before starting installation, TeamForge must be configured to proxy Orchestrate's web traffic. See Proxying Orchestrate through TeamForge and Proxy settings and ports used by TeamForge Orchestrate services.

Download and run install_collabnet-orchestrate-16.3.sh

To gain access to the TeamForge Orchestrate installation script install_collabnet-orchestrate-16.3.sh, contact CollabNet Support
Once Support has given you access, download install_collabnet-orchestrate-16.3.sh from Open CollabNet
Log into the host designated to be the TeamForge Orchestrate application server (App server) with a privileged account.
Copy install_collabnet-orchestrate-16.3.sh to /tmp and change directories to that location.
cp install_collabnet-orchestrate-16.3.sh /tmp

cd /tmp

chmod 755 install_collabnet-orchestrate-16.3.sh

At this point, if the host(s) you are installing on do not have internet access, follow the steps in Installation without internet access before continuing with the next step in this guide.
Run install_collabnet-orchestrate-16.3.sh with root privileges
sudo ./install_collabnet-orchestrate-16.3.sh

The installer then performs the following actions: installs the CollabNet yum repository, installs the collabnet-orchestrate-core RPM, which causes several dependencies to be installed (passenger, ruby, redis, nginx, gems, etc.).
Read the TeamForge Orchestrate license agreement
```
> Do you agree to the terms of the license?
```
Type "Yes" to proceed, or "No" to exit. Once agreed, the installation process continues by asking a series of questions necessary to configure your installation TeamForge Orchestrate.

Installing MongoDB - The first set of questions concerns installation and configuration of MongoDB, the database server.

Install MongoDB or use an existing installation
```
> Do you have an existing MongoDB system you would like to use? [No]:
```
Input "No" unless you have an existing instance of MongoDB you prefer to use. If you input "Yes", reference the documentation in Use an existing MongoDB installation to complete MongoDB configuration, then return to this document and skip to the next section concerning RabbitMQ.
Provide the SSH hostname of target DB server
```
> What is the SSH hostname of your MongoDB host:
```
Enter the hostname of the server that has been designated as the database server (DB server). If installing on a single host, use "localhost".
Provide the SSH username of target DB server
```
> What is the SSH username for your MongoDB host (NOTE: This user needs sudo access):
```
Enter the username to use when installing the MongoDB software on your DB server. This user must be able to connect via SSH to the machine where MongoDB will be installed, even for single-host installations (local SSH). Note, this is the NOT the database user.
Provide SSH key to authenticate DB server, if any
```
> Does this account need an SSH key for authentication [No]:
```
Input "Yes" if you have set up an SSH key for authentication. Note: you will still be prompted for a private password (passphrase), if you set one when you created your private key.
1. If you answered "Yes" above, provide the SSH key location
```
> What is the full path to the SSH key you would like to use [~/.ssh/id_rsa]:
```
  Enter the full path to your private SSH key file (Example: /home/preseed/.ssh/id_rsa). This file must be on the local machine where the installer is running.
  Note: The default here is to use the current user's home directory, which would be root, and may not be the correct SSH key location.
Provide the SSH password
```
> What is the password for the USERNAME user on HOSTNAME []:
```
Please provide a password even if using SSH keys, as the installer will run sudo commands.

Installing RabbitMQ - The following set of questions concerns installation and configuration of RabbitMQ, the message queue service.

Install RabbitMQ or use an existing installation
```
> Do you have an existing RabbitMQ system you would like to use? [No]:
```
Input "No" unless you have an existing instance of RabbitMQ you prefer to use. If you input "Yes", reference the documentation in Use an existing RabbitMQ installation to complete RabbitMQ configuration, then return to this document and skip to the next section concerning TeamForge Orchestrate configuration.
Provide the SSH hostname of target MQ server
```
> What is the SSH hostname of your RabbitMQ host:
```
Enter the hostname of the server that has been designated as the message queue server (MQ server). If installing on a single host, use "localhost".
Provide the SSH username of target MQ server
```
> What is the SSH username for your RabbitMQ host (NOTE: This user needs sudo access):
```
Enter the username to use when installing the RabbitMQ software on your MQ server. This user must be able to connect vian SSH to the machine where RabbitMQ will be installed, even for single-host installations (local SSH).
Provide SSH key to authenticate MQ server, if any
```
> Does this account need an SSH key for authentication [No]:
```
Input "Yes" if you have set up an SSH key for authentication. Note: you will still be prompted for a private password (passphrase), if you set one when you created your private key.
1. If you answered Yes above, provide the SSH key location
```
> What is the full path to the SSH key you would like to use [~/.ssh/id_rsa]:
```
  Enter the full path to your private SSH key file (Example: /home/preseed/.ssh/id_rsa). This file must be on the local machine where the installer is running.
  Note: The default here is to use the current user's home directory, which would be root, and may not be the correct SSH key location.
Provide the SSH password
```
> What is the password for the USERNAME user on HOSTNAME []:
```
Please provide a password even if using SSH keys, as the installer will run sudo commands.
Provide the FQDN of target MQ server
```
> What is FQDN or routable IP of your RabbitMQ host:
```
Enter the hostname of the server that has been designated as the message queue server (MQ server). The MQ component must be network accessible by adapters supplying data to Orchestrate. "localhost" or "127.0.01" values are not permitted, even for single-host installations. We also strongly suggest using a distinct DNS hostname or alias for the MQ component to make host separation easier for scaling in the future.

Configuring TeamForge Orchestrate - The following set of questions concerns the configuration of TeamForge Orchestrate.

Provide the SSH username of target App Server (the local machine)
```
> What is the SSH username for your Orchestrate host (localhost) NOTE: This user needs sudo privileges:
```
Enter the username to use when installing the Orchestrate application on the local server. SSH credentials with sudo root privileges are required at this step even though you are likely installing the App server locally.
Provide SSH key to authenticate App server, if any
```
> Does this account need an SSH key for authentication [No]:
```
Input "Yes" if you have set up an SSH key for authentication. SSH credentials are required even if this is a local installation. Note: you will still be prompted for a private password (passphrase), if you set one when you created your private key.
1. If you answered "Yes" above, provide the SSH key location
```
> What is the full path to the SSH key you would like to use [~/.ssh/id_rsa]:
```
  Enter the full path to your private SSH key file (Example: /home/preseed/.ssh/id_rsa). This file must be on the local machine where the installer is running.
  Note: The default here is to use the current user's home directory, which would be root, and may not be the correct SSH key location.
Provide the SSH password
```
> What is the password for the USERNAME user on HOSTNAME []:
```
Please provide a password even if using SSH keys, as the installer will run sudo commands.
Provide a hostname for your TeamForge Orchestrate service
```
> What hostname should we use for the Orchestrate web service:
```
You should be running the installer on the server designated as the Orchestrate App server; so the answer here would be the DNS hostname entry for the local host. If you're using SSL, the hostname supplied should agree with your certificate. Note that by default end-users will be proxied through the main TeamForge web services, which may be a different DNS name.
Provide port for the Orchestrate web service
```
> What server port should Orchestrate listen on [8844]:
```
By default, the Orchestrate service is proxied through the main TeamForge web server, so end- users will not use this port. However, we recommend sticking with the default 8844. If you modify this default, make sure the new value agrees with the TeamForge site token ORC_PORT in your TeamForge site-options.conf file.
SSL option
```
> Should Orchestrate use SSL?: [Yes]
```
Keeping in mind that end-users will access Orchestrate proxied through TeamForge, select whether you wish to protect the communication between Orchestrate and the TeamForge server with SSL If yes, ensure the value of the TeamForge site token ORC_PROTOCOL is https in your TeamForge site-options.conf file.
Provide location of SSL key (skipped if no SSL)
```
> Where is the SSL key you want to use for Orchestrate located:
```
This key file will be used to configure Orchestrate's web server for . Enter the full path of your locally stored SSL key file (Example: /path/to/server.key). Self-signed certificates are functional.

Important: The SSL certificate may not be password protected or the installation process will fail with an error.
Provide location of SSL certificate (skipped if no SSL)
```
> Where is the SSL certificate you want to use for Orchestrate located:
```
Enter the full path of your locally stored SSL cert file (Example: /path/to/server.crt) and ensure the same certificate file is used with the TeamForge site token ORC_SSL_CA_CERT_FILE in your TeamForge site-options.conf file. Self-signed certificates are functional.
Provide location of CA certificate chain (skipped if no SSL)
```
> Where is the CA certificate chain you want to use for Orchestrate located:
```
Enter the full path of your locally stored CA certificate chain file. This file will be provide by the SSL certificate signing authority used to generate your SSL certificate. If you are using a self-signed certificate then a CA certificate is not required; however, the installation process needs a file here in order to continue, just create an empty file and input the path and name.
touch /path/to/emptyfile

Configuring TeamForge - The following set of questions concerns the configuration of TeamForge.

Provide your TeamForge URL
```
 What is the URL for your TeamForge server:
```
Enter the URL for the TeamForge instance associated with this TeamForge Orchestrate installation.
Provide a TeamForge administrative user account
```
> What administrative user would you like to use to join TeamForge Orchestrate to TeamForge:
```
The installation process requires a TeamForge administrative account so to execute the integration of Orchestrate into TeamForge.

Add this user to the TeamForge site token USERS_WITH_NO_EXPIRY_PASSWORD in your TeamForge site-options.conf file.
Provide the TeamForge administrative user's password
```
> What is the password for the user you entered:
```
The installer will now perform a series of operations; installing and/or configuring MongoDB, RabbitMQ, and the Orchestrate server. When the installer finishes, Orchestrate will be installed and accessible using the TeamForge Orchestrate hostname configured above.