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. Note that some questions have a default answer which is denoted in square brackets.

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

prepare SSH users and passwords/keys. Note that even with SSH keys, user passwords are still required for the installation process.
ensure SSH users have sudo 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).

Download and run install_[version].sh

To gain access to the TeamForge Orchestrate installation script install_[version].sh, contact CollabNet Support
Once Support has given you access, download install_[version].sh from Open CollabNet
where [version] represents the target Orchestrate version.
Log into the host designated to be the TeamForge Orchestrate application server (App server) with a privileged account.
Copy install_[version].sh to /tmp and change directories to that location.
cp install_[version].sh /tmp cd /tmp chmod 755 install_[version].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_[version].sh with root privileges
sudo ./install_[version].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 server:
```
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 server (NOTE: This user needs sudo access):
```
Enter the name of the user to use when installing the MongoDB software on your DB server. This user must be able to connect via SSH to the machine where MongDB will be installed, even for single-host installations (local SSH). This is the NOT the database user.
Provide the SSH password
```
> What is the password for the USERNAME user on HOSTNAME []:
```
Note that the password is required even if using SSH keys. While keys will be used for remote host access, a username and password is still needed for executing privileged (sudo) installation commands.
Provide SSH key to authenticate DB server, if any
```
> Does this account need a SSH key for authentication [No]:
```
Input "Yes" if you have set up your DB server with the current system's public key. Meaning, that you have added your public key for the App server where this script is running into the authorized keys list on the DB server. Allowing you to SSH from this machine into the DB server without supplying a password. 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.

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

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 hostname of target MQ server
```
> What is the hostname 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 so entering "localhost" is not advisable, even for single-host installations. We also suggest using a distinct DNS hostname or alias for the MQ component to make host separation easier for scaling in the future.
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 name of the user to use when installing the RabbitMQ software on your MQ server. This user must be able to connect via SSH to the machine where RabbitMQ will be installed, even for single-host installations (local SSH).
Provide the SSH password
```
> What is the password for the USERNAME user on HOSTNAME []:
```
Note that the password is required even if using SSH keys. While keys will be used for remote host access, a username and password is still needed for executing privileged (sudo) installation commands.
Provide SSH key to authenticate MQ server, if any
```
> Does this account need a SSH key for authentication [No]:
```
Input "Yes" if you have set up your MQ server with the current system's public key. Meaning, that you have added your public key for the App server where this script is running into the authorized keys list on the MQ server. Allowing you to SSH from this machine into the MQ server machine without supplying a password. 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.

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

Provide a hostname for end-user access
```
> What virtual hostname should we use for the Orchestrate web service:
```
Enter the hostname end-users will use to access TeamForge Orchestrate. You should be running the installer on the same machine that is designated as the Orchestrate App server. So the answer here would be the DNS hostname entry for the local host.
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 name of the user to use when installing the Orchestrate application on the local server. SSH credentials are required even if you are installing this component on the current host.
Provide the SSH password
```
> What is the password for the USERNAME user on HOSTNAME []:
```
SSH credentials are required even if this is a local installation. Note that the password is required even if using SSH keys. While keys will be used for remote host access, a username and password is still needed for executing privileged (sudo) installation commands.
Provide SSH key to authenticate App server, if any
```
> Does this account need a SSH key for authentication [No]:
```
Input "Yes" if you have set up a 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 location of SSL key
```
> Where is the SSL key you want to use for Orchestrate located:
```
Enter the full path of your locally stored SSL key file (Example: /path/to/server.key). This key file will be used to configure the Nginx server for SSL support. Self-signed certificates are acceptable.

Important: The SSL certificate may not be password protected or the installation process will fail with an error.
Provide location of SSL certificate
```
> 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). This key file will be used to configure the Nginx server for SSL support. This can be a self signed certificate.
Provide location of SSL certificate
```
> 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 installer 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 USERS_WITH_NO_EXPIRY_PASSWORD section within 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.

Continue with the Post-installation tasks before using TeamForge Orchestrate.