Reveal Help Center

Installation & Upgrade - Brainspace 6.2 through 6.5

Prerequisites

All prerequisites must be satisfied before installing Brainspace software. If you have any issues verifying that you have satisfied these prerequisites, contact Brainspace Customer Service before the scheduled installation.

Operating System and Hardware Validation

This validation ensures that you have all of the necessary software and hardware requirements for a successful Brainspace three-server installation.

Root Access and Third-Party Application Credentials

Customer personnel who will be involved in the installation must have root access to all three servers and administration credentials for any third-party applications involved in the installation.

Brainspace License File

The Brainspace license file is created specifically for your installation. The text file naming convention is <YOUR COMPANY NAME><EXPIRATION DATE>-license.txt.

Note

For the installation call with Brainspace, this file must be in the same directory as the installer file. If you have not received an email with this file, contact Brainspace Support before the installation date.

Brainspace Installation

In versions 6.3.0 and 6.2.12 and older, Brainspace released as a self-extracting shell script. This script’s naming convention was Brainspace-<VERSION-NUMBER>.install, for example, version 6.2.12 would be named Brainspace-6.2.12.install.

In versions 6.3.1 and 6.2.13 and newer, Brainspace releases as a tarball. This tarball’s naming convention is brainspace-<VERSION NUMBER>.tar. For example, version 6.3.1 would be named brainspace-6.3.1.tar.

These files are made available by the Project Managers in your Install or Upgrade ticket and need to be available for the installation or upgrade.

Supported Web Browser

You access the Brainspace software using a web browser. Brainspace supports the following browsers:

Chrome, Firefox, Edge (Chromium based version)

Brainspace 6.3 and newer Specific

The /localdata-share

Brainspace 6.3 requires that /localdata/brainspace on the Application Server be shared to the On-Demand Analytics Server (ODA), and be mounted on the ODA as /localdata-share. More detailed information on configuring this can found in Support Station.

Note

A /localdata-share directory should also be made on the Analytics Server, this will not be a share directory from the Application Server, just a local directory on the Analytics Server.

New Installation
Install the Application Server

After satisfying all prerequisites, install the Application server.

Note

Customer personnel who will be involved in the installation must have root access to all three servers and administration credentials for any third-party applications involved in the installation.

To install the Application (Runtime) server:

  1. Switch to the root user:

    sudo -i

  2. For installations of 6.3.0 or 6.2.12 and older, please skip to #4.

  3. For installations 6.3.1 or 6.2.13 or newer:

    1. Extract the installation tarball.

      tar -vxf brainspace-<VERSION NUMBER>.tar

    2. Change to the installation directory and start the installer:

      cd brainspace-<VERSION NUMBER> && bash install-rpm.sh

    3. Skip to #5.

  4. For installations 6.3.0 or 6.2.12 or older:

    1. To make the install script executable, type the following command: chmod +x Brainspace-<VERSION-NUMBER>.install

    2. In the directory where the installer is located, execute the following installation script to create your directory structure: ./Brainspace-<VERSION-NUMBER>.install

      Note

      To unpack the installer to a directory other than /tmp, specify an argument as shown in the following example:

      ./Brainspace-<VERSION-NUMBER>.install /data

      Note

      You can exit the installer at any time. To restart the installation, execute the BASH script located in the /tmp/Brainspace-<VERSION-NUMBER>/installer-ui.sh

      ApplicationInstall01.png
  5. With APPLICATION Server highlighted, press Enter on your keyboard.

  6. The Set Database Password dialog box will appear, press Enter:

    Set_Database_Password_Infobox.png
  7. Enter a password for the PostgreSQL database user, then press Enter:

    Note

    You will use this password on all 3 servers and it can only be Alpha numeric, no special characters.

    Enter_Password.png
  8. Re-enter the password:

    Enter_Password2.png
  9. When installation completes you will be presented with the following, giving the URL for accessing the UI as well as the default Username and password:

    Installation_command_line.png
  10. Copy the license file from the installation directory to

    /var/lib/brains/.brainspace/Brainspace_license.txt

    The following is an example of how to copy the license to the target location from the

    installation directory:

    cp <YOUR COMPANY NAME><EXPIRATION DATE>-license.txt

    /var/lib/brains/.brainspace/brainspace_license.txt

    To overwrite the default license file, enter yes.

    Note

    If SELinux is enabled, SELinux must be configured to allow HAProxy to connect to Tomcat via TCP.

    One way to do this is to use the following command:

    setsebool -P haproxy_connect_any 1

After successfully installing the Application server, you will install the Analytics server and then the On-Demand servers.

Install the Analytics Server and On-Demand Analytics Server

After successfully installing the Application server, you will install the Analytics (Build) server and then the On-Demand server.

Note

The following installation procedure is identical for the Analytics and On-Demand Analytics servers. After installing the Analytics server, repeat the procedure for the OnDemand Analytics server.

To Install the Analytics server

  1. Switch to the root user:

    sudo -i

  2. For installation of version 6.3.0 or 6.2.12 or older, please skip to #4.

  3. For installation of version 6.3.1 or 6.2.13 or newer, step (a) can be skipped if you extracted to a network mount available to this server in the Install Application phase:

    1. Extract the installation tarball.

      tar -vxf brainspace-<VERSION NUMBER>.tar

    2. Change to the installation directory and start the installer: cd brainspace-<VERSION NUMBER> && bash install-rpm.sh

    3. Skip to #5.

  4. For installation of version 6.3.0 or 6.2.12 or older:

    1. To make the install script executable, type the following command: chmod +x Brainspace-<VERSION-NUMBER>.install

    2. In the directory where the installer is located, execute the following installation script to create your directory structure: ./Brainspace-<VERSION-NUMBER>.install

      Note

      To unpack the installer to a directory other than /tmp, specify an argument as shown in the following example:

      ./Brainspace-<VERSION-NUMBER>.install /data

      Note

      You can exit the installer at any time.

      To restart the installation, execute the Bash script located in the /tmp/Brainspace-<VERSION-NUMBER>/installer-ui.sh directory.

  5. Select ANALYTICS/BUILD with the down-arrow, and then press Enter on your keyboard. The Set Database Password dialog will open.

    ApplicationInstall01.png
  6. Enter the password that you set up for the Brainspace PostgreSQL password from the Application (Runtime) server, and then press Enter on your keyboard:

    Enter_Password.png
  7. Re-enter the password, and then press Enter on your keyboard:

    Enter_Password2.png
  8. Enter the IP address or fully-qualified domain name for the Application server, and then press Enter on your keyboard:

    Server_Hostname_entry.png
  9. On the ODA & Analytics Servers, for 6.3 installs, when prompted enter the location of

    App_Server_mount_directory.png

    Note

    The share from the Application Server should be /localdata/brainspace and the mount point on the ODA should be /localdata-share.

    Note

    This will be asked for on the Analytics Server, however this just needs to be a directory on the Analytics Server and does NOT have to be a share from any other server. This can be set to /localdata on the Analytics Server ONLY.

  10. Copy the license file from the installation directory to /var/lib/brains/.brainspace/brainspace_license.txt

    The following is an example of how to copy the license to the target location from the installation directory:

    cp <YOUR COMPANY NAME><EXPIRATION DATE>-license.txt /var/lib/brains/.brainspace/brainspace_license.txt

  11. To overwrite the default license file, enter yes.

After successfully installing the Analytics server, repeat this procedure to install the On-Demand Analytics server.

Test the Brainspace License File

After installing the Application (Runtime) server, Analytics (Build) server, and the On-Demand Analytics (Analytics) server, you must verify that your Brainspace license file is recognized by the servers.

Note

You must test the license file on all three servers.

  1. Execute the following command to login as root: su -i

  2. Verify that the brains user has ownership and read permissions of the license file: ls -l /var/lib/brains/.brainspace/brainspace_license.txt.

    Note

    If the license is not owned by the brains user, change ownership using the following command: chown brains:brains /var/lib/brains/.brainspace/brainspace_license.txt.

  3. To log in as the brains user, execute the following command: su - brains (The dash is important)

    The screen will show that you are now user brains as shown in the following example:

    Brains_screen.png
  4. To determine if the Brainspace license is recognized and correctly matches the license terms, execute:

    bt info

    The screen will show information about your license file, including the expiration date, as shown in the following example:

    Command_line_license_file_info.png

After successfully testing the Brainspace license on the Application server, repeat this procedure to verify that the license file is recognized on the Analytics server and the OnDemand Analytics server.

After successfully testing the Brainspace license on all three servers, you are ready to log in to Brainspace for the first time.

Log into Brainspace

After successfully testing the Brainspace license on all three servers, you are ready to log in to Brainspace for the first time.

To login to Brainspace:

  1. In the URL line of your web browser, enter the IP address or fully-qualified domain name for the Application server, and then press Enter on your keyboard. The web browser will load the Brainspace login screen:

    Brainspace_login_screen.png
  2. Type support@brainspace.com as the email address and system1 as the password. The Change Your Password dialog will open.

  3. Create a new password, and then click Change Password.

After logging in to Brainspace and changing your password, you are ready to register the Analytics server and On-Demand Analytics server.

Register the Analytics Server and On-Demand Analytics Server

After logging in to Brainspace and changing your password, you are ready to register the Analytics server first and then the On-Demand Analytics server.

Note

The following installation procedure is identical for the Analytics server and On-Demand Analytics server.

To add the Analytics server first:

  1. In the user drop-down menu, click Administration:

    image1.jpeg

    The Datasets screen will open.

  2. Click the Services button:

    Small_Services_button.png
  3. Click the +Service button:

    services_screen.png

    The Services screen will open.

  4. In the Service URL field, type the IP address or fully-qualified domain name of your Analytics server prefixed with https:// and suffixed with the port number 1604.

    Note

    If using the IP address, the URL should be similar to the following example: https://10.8.2.202:1604.

    If using the fully-qualified domain name, the URL should be similar to the following example: https://my-analytics-server.example.com:1604.

  5. Click the Service Type drop-down menu, and then select Brainspace Analytics.

  6. In the Service Name field, type a name for the server.

    If connectivity to the Brainspace Analytics server from the Application (Runtime) server was successfully established, a check mark will display with the server, as shown in the following example:

    Service_name_entry.png
  7. Click the Save Service button: Your Analytics server will appear on the Services screen.

  8. Verify that the installed Brainspace version number appears with the server, as shown in the following example:

    Server_version_numbers.png

    After successfully registering the Analytics server, repeat this procedure for the On-Demand Analytics server.

If your servers are not registered correctly or if you have problems loading your servers, contact Brainspace Support.

After successfully installing the Application server, Analytics server, and the On-Demand Analytics server, you will set up the first Brainspace user and create a dataset. For details, see Datasets.

Upgrading
Upgrading Application Server

If this is an upgrade to 6.3 then ensure that NFS is running on the Application Server with systemctl status nfs, if it is not then start it with systemctl start nfs. Also ensure that /etc/exports has the entry to share /localdata/brainspace to the ODA Server.

  1. Switch to the root user:

    sudo -i

  2. If there is a custom SSL certificate make a copy of this for later (step 10):

    1. Change to /etc/brainspace/ssl directory

      cd /etc/brainspace/ssl

    2. Copy the brainspace_ss.pem file to /tmp

      cp brainspace_ss.pem /tmp

  3. For installation of version 6.3.0 or 6.2.12 or older, please skip #4.

  4. For upgrades to 6.3.1 or 6.2.13 or newer:

    1. Extract the installation tarball.

      tar -vxf brainspace-<VERSION NUMBER>.tar

    2. Change to the installation directory and start the installer:

      cd brainspace-<VERSION NUMBER> && bash install-rpm.sh

    3. Skip to #6.

  5. For upgrades to 6.3.0 or 6.2.12 or older:

    1. To make the install script executable, type the following command:

      chmod +x Brainspace-<VERSION-NUMBER>.install

    2. In the directory where the installer is located, execute the following installation script to create your directory structure:

      ./Brainspace-<VERSION-NUMBER>.install

      Note

      To unpack the installer to a directory other than /tmp, specify an argument as shown in the following example:

      ./Brainspace-<VERSION-NUMBER>.install /data

      Note

      You can exit the installer at any time. To restart the installation, execute the BASH script located in the /tmp/Brainspace-<VERSION-NUMBER>/installer-ui.sh.

  6. After the installer is started, the following menu will open:

    Upgrade_App_Server.png
  7. With APPLICATION Server highlighted, press Enter on your keyboard.

  8. When installation completes you will be presented with the following, giving the URL for accessing the UI as well as the default Username and password:

    Command_line_Upgrade_Complete.png
  9. If you had a custom SSL cert and made a copy of it:

    1. Go to /tmp

      cd /tmp

    2. Copy the brainspace_ss.pem to /etc/brainspace/ssl

      cp brainspace_ss.pem /tmp/

    3. Verify the pem file has your custom information:

      cd /etc/brainspace/ssl

      openssl verify brainspace_ss.pem

    4. Restart brainspace-haproxy for the copied ssl cert to take effect

      systemctl restart brainspace-haproxy

Upgrading Analytics & On-Demand Analytics

Note

You will need a /localdata-share directory on the Analytics Server, this should NOT be an NFS mount like it is on the On-Demand Analytics Server.

  1. Switch to the root user:

    sudo -i

  2. For installation of version 6.3.0 or 6.2.12 or older, please skip to #4.

  3. For upgrades to 6.3.1 or 6.2.13 or newer, step (a) can be skipped if you extracted to a network mount available to this server in the Upgrading Application Server phase:

    1. Extract the installation tarball.

      tar -vxf brainspace-<VERSION NUMBER>.tar

    2. Change to the installation directory and start the installer:

      cd brainspace-<VERSION NUMBER> && bash install-rpm.sh

    3. Skip to #5.

  4. For upgrades to 6.3.0 or 6.2.12 or older:

    1. To make the install script executable, type the following command:

      chmod +x Brainspace-<VERSION-NUMBER>.install

    2. In the directory where the installer is located, execute the following installation script to create your directory structure:

      ./Brainspace-<VERSION-NUMBER>.install

      Note

      To unpack the installer to a directory other than /tmp, specify an argument as shown in the following example:

      ./Brainspace-<VERSION-NUMBER>.install /data

  5. Highlight ANALYTICS/BUILD, and then press Enter on your keyboard.

    Upgrade_Analytics.png
  6. For 6.3 upgrades you will see the below prompt for the location of the localdata-share:

    App_Server_mount_directory.png

    Note

    The share from the Application Server should be /localdata/brainspace and the mount point on the ODA should be /localdata-share.

  7. After the upgrade completes successfully you will see a message similar to what is seen on the Application Server.

Confirmations After Upgrading

After you’ve upgraded all servers you will want to do the following to confirm everything is working as expected:

  1. Login to Brainspace with your credentials:

    Brainspace_login_-_small.jpg
  2. Go to “Administration” and then to the “Services Tab”:

    image1.jpeg
    Services_tab.png
  3. Confirm all Services are on the same version and that the Services are all showing “Active” and “READY”:

    Services_ready_table.png
Post Installation/Upgrade Checks

Note

For upgrades where a test dataset already exists and can be used, you can skip past the “Create ENRON Dataset” header.

Copy the ENRON .dat file
  1. For new installations or installations where the ENRON .dat file was not retained, a copy is included with our installation. On the Application server, change inside the install directory.

  2. Within the install directory will be a “datasets” subdirectory, and inside of there is the enron-10k-2.0.dat file.

  3. Copy the enron-10k-2.0.dat file to /data/brainspace cp datasets/enron-10k-2.0.dat /data/brainspace

  4. Change the ownership of the enron-10k-2.0.dat file to brains:brains to ensure Brainspace can read the file.

    chown brains:brains /data/brainspace/enron-10k-2.0.dat

Creating the DAT Connector
  1. If a DAT connector does not exist, create one now. On the Connectors page click the “+ Connector” button, then “DAT” from the Dropdown menu.

    Connectors_page_and_button.png
  2. Give it a name, for example “DAT”. Set the “Offset Path from” field to a period. Then click Create Connector.

    Name_DAT_connector.png
Create ENRON Test Dataset
  1. From the Admin Datasets dashboard, click the “+ Dataset” button.

  2. Name the Dataset, we typically name it along the lines of “ENRON Test” to designate it’s a test dataset, or “ENRON 10k”. Then click “Create”.

    Create_Enron_Dataset.png
  3. On the next screen, click “Choose Connector”.

    Choose_connector.png
  4. Select the DAT Connector:

    Select_DAT_connector.png
  5. Select “DAT Source” then click the “Save & Proceed” button:

    Select_DAT_Source.png
  6. Click the “Browse” button on the next modal and select the enron-10k-2.0.dat file. After selecting the file and clicking the “Select” button, the modal should look like this:

    Proceed_DAT_Source_Connector.png
  7. Click “Proceed”. Verify the license checks shows 10,000 documents and click “Proceed” to continue to field mapping.

  8. Map your fields to match:

    Map_DAT_source_fields.png
  9. Click “Continue” and then “Save” on the dataset configuration modal to save your settings.

Build the ENRON Test Dataset
  1. From the dataset configuration modal, click the “Build” button. This step is used to verify the Analytics server.

    Select_Build_Test_Dataset.png
  2. If this is the first time building this dataset, you will need to do a “Full Analytics with Ingest”, otherwise it is sufficient to run “Full Analytics without Ingest” to complete a test build. Click “Run This Build Type” next to the appropriate build option followed by “Build as soon as possible”.

    Test_Dataset_Build_Options.png
  3. Ideally, this build should complete within 7 minutes. Any longer could signify a potential bottleneck in infrastructure resources like storage, CPU or RAM availability.

    Note

    If an ingest is performed while the Application server is starting up datasets after an upgrade, this time is expected to be affected due to the load of the Application server.

  4. Once the build is complete, open the Analytics for the dataset.

    1. Check the Cluster Wheel to ensure it loaded terms.

    2. Check Communications to ensure it identified people and loaded connections between them.

  5. Create a test Focus to ensure the connection to the On-Demand Analytics server. Run a Concept Search on a concept, for example: Party. Once that is loaded, created a focus and name it something along the lines of “Test Focus” to signify it is for testing.

    Create_Test_Focus.png
  6. Use the “Select a Focus” dropdown to monitor progress of the focus. You can use the “Refresh” button to check the progress. The Focus build can take 3-5 minutes, or longer, depending on the concept search used and the number of documents.

    Select_Test_Focus.png
  7. Once the focus is built, run the same checks you did in #4 after selecting the focus.

  8. Install/Upgrade checks are complete and the services are operational.

Document Revision Table

Date

Author

Revision Details

7/2/2020

Nick McKin

Initial

7/30/2020

Daniel Hawton

Added instructions for 6.3.1 and 6.2.13 and newer, revised a bit of the wording, fixed page numbers to start with “2” to line up PDF page numbers with page numbers on the page, and added ENRON checks

4/15/2021

Nick McKin

Added steps in the upgrade portion for copying and re­applying custom ssl certs.

5/3/2021

Nick McKin

Removed step for adding “ssl=true”. Added Reveal-Brainspace branding

6/2/2021

Andrew Kass

Extracted, formatted and migrated to Paligo XML.