Installing HCI

To install a system, you need the HCI-<version-number>.tgz file.

This archive file includes the software installation files needed to install your HCI instance.

Parent Topic

• Installing HCI

To utilize the Solr backup and restore functionality of HCI, the following prerequisites need to be met on your system:

1. An external, dedicated NFS mount point for each HCI cluster.
2. A directory created on each node in your HCI cluster called solrBackups, located at the following path: install_path/solrBackups
3. The file system from step 1 mounted on each node of the directory listed in step 2.
   NoteThe mechanism used to mount the file system needs to be able to persist through node reboot.
4. Sufficient disk space available on the mounted file system in order to successfully backup your HCI index.
5. Sufficient disk space reserved on your HCI nodes in order to successfully restore your HCI index.

It is recommended that all of the above mentioned mount points be set up prior to your installation of HCI.

For more information about Solr backup and restore after installing HCI, refer to the Workflow Designer Help.

Parent Topic

• Installing HCI

HCI installation consists of the following steps:

1. Decide how many instances to deploy
2. Configure your networking environment
3. Optional: Select master instances
4. Install Docker on each server or virtual machine
5. Configure Docker on each server or virtual machine
6. Optional: Install Docker volume drivers
7. Optional: Enable or disable SELinux on each server or virtual machine
8. Configure maximum map count setting
9. Configure the firewall rules on each server or virtual machine
10. Run Docker on each server or virtual machine
11. Unpack the installation package
12. (Optional) Reconfigure network.config on each server or virtual machine
13. (Optional) Reconfigure volume.config on each server or virtual machine
14. Run the setup script on each server or virtual machine
15. Start the application on each server or virtual machine
16. Optional: Configure NTP
17. Access deployment wizard
    1. (optional) Configure service networking
    2. (optional) Configure volumes for services and jobs
18. Deploy the system
19. Verify the created volumes
20. Distribute services among system instances
21. Configure the system for your users

Parent Topic

• Installing HCI

Procedure

1. Decide how many instances you need.

2. Select the servers or virtual machines in your environment that you intend to use as HCI instances.

Parent Topic

• Installing HCI

Procedure

1. Determine what ports each HCI service should use. You can use the default ports for each service or specify different ones.

   In either case, these restrictions apply:
   • Every port must be accessible from all instances in the system.
   • Some ports must be accessible from outside the system.
   • All port values must be unique; no two services, whether System services or HCI services, can share the same port.

2. Determine what types of networks, either internal or external, to use for each service.

   If you're using both internal and external networks, each instance in the system must have IP addresses on both your internal and external networks.

Parent Topic

• Installing HCI

Procedure

1. Select which of the instances in your system are intended as master instances.

2. Make note of the master instance IP addresses.

   NoteTo ensure system availability, run master instances on separate physical hardware from each other, if possible.

Parent Topic

• Installing HCI

Procedure

1. In a terminal window, verify whether Docker 1.13.1 or later is installed:

   docker --version

2. If Docker is not installed or if you have a version before 1.13.1, install the current Docker version suggested by your operating system.

   The installation method you use depends on your operating system. See the Docker website for instructions.

Parent Topic

• Installing HCI

Procedure

1. Ensure that the Docker installation folder on each instance has at least 20 GB available for storing the product Docker images.

2. Ensure that the Docker storage driver is configured correctly on each instance. After installation, changing the Docker storage driver needs reinstallation of the product.

   To view the current Docker storage driver on an instance, run: docker info .

3. To enable SELinux on the system instances, use a Docker storage driver that SELinux supports.

   The storage drivers that SELinux supports differ depending on the Linux distribution you're using. For more information, see the Docker documentation.

4. If you are using the Docker devicemapper storage driver, ensure that there's at least 40 GB of Docker metadata storage space available on each instance.

   The product needs 20 GB to install successfully and an additional 20 GB to successfully update to a later version.To view Docker metadata storage usage on an instance, run: docker info

Next steps

Parent Topic

• Installing HCI

Procedure

1. If any services on your system are using Docker volume drivers (not the bind-mount setting) for storing data, install those volume drivers on the new instance that you are adding.

   If you don't, services might fail to run on the new instance.

2. If any services on your system use Docker volume drivers for storing data (instead of using the default bind-mount setting), install those volume drivers on all instances in the system.

Parent Topic

• Installing HCI

Procedure

1. Enable or disable SELinux on each instance.

2. Restart the instance.

Parent Topic

• Installing HCI

Procedure

1. On each server or virtual machine that is to be a system instance, open the file /etc/sysctl.conf.

2. Append this line: vm.max_map_count = 262144

   If the line already exists, ensure that the value is greater than or equal to 262144.

3. Save and close the file.

Parent Topic

• Installing HCI

Procedure

1. Verify that Docker is running:

   systemctl status docker

2. If Docker is not running, start the docker service:

   sudo systemctl start docker

3. (Optional) Configure the Docker service to start automatically when you restart the server or virtual machine:

   sudo systemctl enable docker

Parent Topic

• Installing HCI

Procedure

1. Download the product installation package and MD5 checksum file and store both in a folder on the server or virtual machine.

2. Verify the integrity of the installation package:

   md5sum -c HCI-version_number.tgz.md5If the package integrity is verified, the command displays OK.

3. In the largest disk partition on the server or virtual machine, create a product installation folder.

   mkdir install_path/hci

4. Move the installation package from the folder where you stored it to the product installation folder.

   mv HCI-version_number.tgz install_path/hci/HCI-version_number.tgz

5. Navigate to the installation folder.

   cd install_path/hci

6. Unpack the installation package:

   tar -zxf HCI-version_number.tgzA number of directories are created within the installation folder.

7. Run the install script:

   sudo ./install
   Notes

   • Don't change directories after running the installation script. The following tasks are performed in your current folder.
   • The installation script can be run only one time on each instance. You cannot rerun this script to try to repair or upgrade a system instance.

Parent Topic

• Installing HCI

Before you begin

Procedure

1. Edit the firewall rules to allow communication over all network ports that you want your system to use. You do this using a firewall management tool such as firewalld.

2. Restart the server or virtual machine.

Parent Topic

• Installing HCI

Before you begin

Procedure

1. On each server or virtual machine that is to be an HCI instance, use a text editor to open the file install_path/hci/config/network.config.

   The file contains two types of lines for each service:
   • Network type assignments:

     com.hds.ensemble.plugins.service.service_name_interface=[internal|external]

     For example:

     com.hds.ensemble.plugins.service.zookeeper_interface=internal

   • Port number assignments:

     com.hds.ensemble.plugins.service.service_name.port.port_name=port_number

     For example:

     com.hds.ensemble.plugins.service.zookeeper.port.PRIMARY_PORT=2181

2. Type new port values for the services you want to configure.

   NoteIf you reconfigure service ports, make sure that each port value you assign is unique across all services, both System services and HCI services.
   NoteBy default, all System services are set to internal.

   If you're only using a single network, you can leave these settings as they are. This is because all system instances are assigned both internal and external IP addresses in HCI; if you're only using a single network type, the internal and external IP addresses for each instance are identical.

3. On the lines containing _interface, specify the network that the service should use. Valid values are internal and external.

4. Save your changes and exit the text editor.

Next steps

Parent Topic

• Installing HCI

Before you begin

Procedure

1. On each server or virtual machine that is to be an HCI instance, use a text editor to open the file install_path/hci/config/volume.config.

   This file contains information about the volumes used by the System services. For each volume, the file contains lines that specify the following:
   • The name of the volume:

     com.hds.ensemble.plugins.service.service_name.volume_name=volume_name

     NoteDo not edit the volume names. The default volume name values contain variables (SERVICE_PLUGIN_NAME and INSTANCE_UUID) that ensure that each volume gets a unique name.
   • The volume driver that the volume uses:

     com.hds.ensemble.plugins.service.service_name.volume_driver=[volume_driver_name | bind-mount]

   • The configuration options used by the volume driver. Each option is listed on its own line:

     com.hds.ensemble.plugins.service.service_name.volume_driver_opt_option_number=volume_driver_option_and_value

     For example, these lines describe the volume that the Admin-App service uses for storing its logs:

     com.hds.ensemble.plugins.service.adminApp.log_volume_name=SERVICE_PLUGIN_NAME.INSTANCE_UUID.log
     com.hds.ensemble.plugins.service.adminApp.log_volume_driver=bind-mount
     com.hds.ensemble.plugins.service.adminApp.log_volume_driver_opt_1=hostpath=/home/hci/log/com.hds.ensemble.plugins.service.adminApp/

2. For each volume that you want to configure, you can edit the following:

   • The volume driver for the volume to use. To do this, replace bind-mount with the name of the volume driver you want.

     Volume drivers are provided by Docker and other third-party developers, not by the HCI system itself. For information on volume drivers, their capabilities, and their valid configuration settings, see the applicable Docker or third-party developer's documentation.

   • On the line that contains _opt, the options for the volume driver.

     For information about the options you can configure, see the documentation for the volume driver that you're using.

     CautionOption/value pairs can specify where data is written in each volume. These considerations apply:

     • Each volume that you can configure here must write data to a unique location.
     • The SERVICE_PLUGIN and INSTANCE_UUID variables cannot be used in option/value pairs.
     • Make sure the options and values you specify are valid. Incorrect options or values can cause system deployment to fail or volumes to be set up incorrectly. For information on configuration, see the volume driver's documentation.
     TipCreate test volumes using the command docker volume create with your option/value pairs. Then, to test the volumes you've created, run the command docker run hello-world with the option --volume.

com.hds.ensemble.plugins.service.marathon.data_volume_name=SERVICE_PLUGIN_NAME.INSTANCE_UUID.data
com.hds.ensemble.plugins.service.marathon.data_volume_driver=local-persist
com.hds.ensemble.plugins.service.marathon.data_volume_driver_opt_1=mountpoint=/home/hci/data/com.hds.ensemble.plugins.service.marathon/

Parent Topic

• Installing HCI

Before you begin

Procedure

1. Run the script setup with the applicable options:

   Option	Description
   -i	The external network IP address for the instance on which you're running the script.
   -I	The internal network IP address for the instance on which you're running the script.
   -m	Comma-separated list of external network IP addresses of each master instance.
   -M	Comma-separated list of internal network IP addresses of each master instance.
   -i IPADDRESS	Displays the external instance IP address. If not specified, this value is discovered automatically.
   -I IPADDRESS	Displays the internal instance IP address. If not specified, this value is the same as the external IP address.
   -d	Attempts to automatically discover the real master list from the provided masters.
   –-hci_uid UID	Allows you to set the desired user ID (UID) for the HCI USER at install time only. ImportantThis value needs to be greater than 1000, less than or equal to 65533, and the same on all nodes in a cluster.
   --hci_gid GID	Allows you to set the desired group ID (GID) for the HCI GROUP at install time only. ImportantThis value needs to be greater than 1000, less than or equal to 65533, and the same on all nodes in a cluster.
   --mesos_uid UID	Allows you to set the desired user UID for the MESOS USER at install time only. ImportantThis value needs to be greater than 1000, less than or equal to 65533, and the same on all nodes in a cluster.
   --mesos_gid GID	Allows you to set the desired GID for the MESOS GROUP at install time only. ImportantThis value needs to be greater than 1000, less than or equal to 65533, and the same on all nodes in a cluster.
   --haproxy_uid UID	Allows you to set the desired UID for the HAPROXY USER at install time only. ImportantThis value needs to be greater than 1000, less than or equal to 65533, and the same on all nodes in a cluster.
   --haproxy_gid GID	Allows you to set the desired GID for the HAPROXY GROUP at install time only. ImportantThis value needs to be greater than 1000, less than or equal to 65533, and the same on all nodes in a cluster.
   --zk_uid UID	Allows you to set the desired UID for the ZOOKEEPER USER at install time only. ImportantThis value needs to be greater than 1000, less than or equal to 65533, and the same on all nodes in a cluster.
   --zk_gid GID	Allows you to set the desired GID for the ZOOKEEPER GROUP at install time only. ImportantThis value needs to be greater than 1000, less than or equal to 65533, and the same on all nodes in a cluster.

   Use the following table to determine which options to use:

   Number of instances in the system	Network type usage	Options to use
   Multiple	Single network type for all services	Either: -i and -m or -I and -M
   Multiple	Internal for some services, external for others	All of these: -i, -I, -m, -M
   Single	Single network type for all services	Either -i or -I
   Single	Internal for some services, external for others	Both -i and -I

Results

Parent Topic

• Installing HCI

1. Start the application script run using whatever methods you usually use to run scripts.

   ImportantEnsure that the method you use can keep the run script running and can automatically restart it in the event of a server restart or other availability event.
   • You can run the script in the foreground: sudo install_path/hci/bin/run

     When executed this way, the run script does not automatically complete, but instead remains running in the foreground.

   • You can run the script as a service using systemd:
     1. Open the HCI.service file in a text editor, located in install_path/bin.
     2. Verify that the following two lines have the correct install_path:

        ExecStart=install_path/hci/bin/run

        ExecStopPost=install_path/hci/bin/stop

     3. Save the file.
     4. Copy the HCI.service file to the appropriate location for your OS:

        cp install_path/hci/bin/HCI.service /etc/systemd/system

     5. Enable and start HCI.service:

        sudo systemctl daemon-reload
        sudo systemctl enable HCI.service
        sudo systemctl start HCI.service

   NoteWhen you enable HCI.service, systemctl might display this message:

   The unit files have no [Install] section. They are not meant to be enabled using systemctl. Possible reasons for having this kind of units are:

   1) A unit may be statically enabled by being symlinked from another unit's .wants/ or .requires/ directory.

   2) A unit's purpose may be to act as a helper for some other unit which has a requirement dependency on it.

   3) A unit may be started when needed via activation (socket, path, timer, D-Bus, udev, scripted systemctl call, ...).

   Depending on your OS, HCI.service may or may not have successfully been enabled.

   To avoid this, make sure that you move HCI.service to the appropriate location, typically /etc/systemd/system.

Parent Topic

• Installing HCI

Procedure

1. Configure NTP (network time protocol) so that each instance uses the same time source.

   For information on NTP, see http://support.ntp.org/.

Parent Topic

• Installing HCI

Procedure

1. Open a web browser and go to: https://instance_ip_address:8000

2. On the Welcome page, set a password for the admin user account. Then click Set Admin Password.

   ImportantDo not lose or forget this password.

3. On the Licensing page:

   • If you have your purchased license file, drag and drop it into the Upload License section.
   • If you've purchased a license but have not yet received it, make note of the value in the System ID section on the Licensing page and contact your sales representative.
   • To use the system for a limited amount of time with the pre-installed trial license, click Continue.
   • If for some reason the trial license failed to install, there is a copy included in the HCI-<version-number>.tgz installation package that you can upload to the Licensing page. The trial license is located in the installation package at:

     install_path/product/<version>/trial-<version>.plk

4. On the Set Cluster Hostname/IP page, specify the hostname for your system. Omitting this can cause links in the Admin App to function incorrectly.

5. On the Choose Deployment page, select the HCI deployment type that you purchased, either Hitachi Content Search or HCM. Then click Continue.

6. The Confirm Cluster Topology page shows all detected instances. If your system includes multiple instances, make sure that all instances that you expect to see are listed.

Parent Topic

• Installing HCI

Child Topics

• (optional) Configure service networking
• (optional) Configure volumes for services and jobs
• Considerations for option/value pairs

Procedure

1. Click Deploy Single Instance or Deploy Cluster (multi-instance), as appropriate.

   The system deployment starts.

2. Click the link View Deployment Details to view the progress of the deployment.

Parent Topic

• Installing HCI

Procedure

1. Stop the run script from running. You do this using whatever method you're currently using to run the script.

2. Run this command to stop all Content Intelligence Docker containers on the instance: sudo install_path/hci/bin/stop

3. Delete the contents of the folder install_path/hci from all instances.

4. Delete any Docker volumes created during the installation: docker volume rm volume_name

5. Begin the installation again from Unpack the installation package.

Parent Topic

• Installing HCI

By default, when you install and deploy a multi-instance system, the system automatically runs each service (except Dashboard) on its required number of instances. For example, the Index service runs on three instances.

However, if you've installed more than four instances, some instances might not be running any services at all. As a result, these instances are underused. You should manually distribute services to run across all instances in your system.

Parent Topic

• Installing HCI

Child Topics

• Moving and scaling floating services
• Moving and scaling services with multiple types
• Best Practices
• Considerations
• Relocating services

Parent Topic

• Installing HCI