EventQ installation walk-through

Installation instructions for TeamForge EventQ.

This guide is a step-by-step walk-through of the TeamForge EventQ 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 EventQ 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 EventQ's web traffic. See Proxying EventQ through TeamForge and Ports used by TeamForge EventQ services.

Install EventQ: Do this on the EventQ Server (server-02)

Configure your TeamForge installation repository.
- TeamForge installation repository configuration for sites with internet access
1. Contact the CollabNet Support and download the TeamForge 17.11.xx installation repository package to /tmp.
2. Install the repository package.
  - yum install -y /tmp/collabnet-teamforge-repo-17.11.xx-1.noarch.rpm
3. Refresh your repository cache.
  - yum clean all
- TeamForge installation repository configuration for sites without internet access
1. Contact the CollabNet Support to get the auxiliary installer package for TeamForge 17.11.xx disconnected installation and save it in /tmp.
  - Red Hat Enterprise Linux/CentOS 7.4 64 bit RPM package: CTF-Disconnected-media-17.11.501-841.rhel7.x86_64.rpm
    Note: In addition to the above CentOS 7.4 64 bit RPM package, you must get the following CentOS 7.4 compatibility RPM, which is required for TeamForge 17.11.xx disconnected media installation on CentOS 7.4 profile: compat-ctf-dc-media-1.0-1.el7.centos.noarch.rpm.
2. Unpack the disconnected installation package.
  - rpm -ivh <package-name>
3. Unpack the compat-ctf-dc-media-1.0-1.el7.centos.noarch.rpm package if you are installing TeamForge 17.11.xx on CentOS 7.4.
  - rpm -ivh compat-ctf-dc-media-1.0-1.el7.centos.noarch.rpm
4. Note: If the Red Hat Enterprise Linux/CentOS installation DVD is mounted already, skip the following instructions. If not, mount the DVD.
  Mount the Red Hat Enterprise Linux/CentOS installation DVD. The DVD contains the necessary software and utilities required for installing TeamForge without internet access.
  In the following commands, replace "cdrom" with the identifier for your server's CD/DVD drive, if necessary.
  - cd /media/
  - mkdir cdrom
  - mount /dev/cdrom ./cdrom/
  If there are any spaces in the automount, unmount it first and mount it as a filepath, with no spaces.
5. Create a yum configuration file that points to the Red Hat Enterprise Linux/CentOS installation DVD.
  - vi /etc/yum.repos.d/cdrom.repo
  Here's a sample yum configuration file.
```
[RHEL-CDROM] 
name=RHEL CDRom 			
baseurl=file:///media/cdrom/Server/
gpgfile=file:///media/cdrom/RPM-GPG-KEY-redhat-release 
enabled=1
gpgcheck=0
```
6. Verify your yum configuration files.
  - yum list httpd
  - yum list apr
Once the yum repository is configured, install the EventQ RPM.
- yum install CN-eventq
Run install-eventq-17.11.sh with root privileges
/opt/collabnet/eventq/bin/install-eventq-17.11.sh

The installer installs several dependencies such as Passenger, Ruby, Redis, Nginx, Gems, etc.

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 EventQ 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 via 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 EventQ. "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 EventQ - The following set of questions concerns the configuration of TeamForge EventQ.

Provide the SSH username of target App Server (the local machine)
```
> What is the SSH username for your EventQ host (localhost) NOTE: This user needs sudo privileges:
```
Enter the username to use when installing the EventQ 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 EventQ service
```
> What hostname should we use for the EventQ web service:
```
You should be running the installer on the server designated as the EventQ 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 EventQ web service
```
> What server port should EventQ listen on [8844]:
```
By default, the EventQ 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 EventQ use SSL?: [Yes]
```
Keeping in mind that end-users will access EventQ proxied through TeamForge, select whether you wish to protect the communication between EventQ 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 EventQ located:
```
This key file will be used to configure EventQ'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 EventQ 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 EventQ 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 EventQ installation.
Provide a TeamForge administrative user account
```
> What administrative user would you like to use to join TeamForge EventQ to TeamForge:
```
The installation process requires a TeamForge administrative account so to execute the integration of EventQ 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 EventQ servers. When the installer finishes, EventQ will be installed and accessible using the TeamForge EventQ hostname configured above.