Update the Aternity Docker Components Server

The Aternity Docker Components Server is the on-premise server that hosts all Aternity Docker services which provide multiple different functionalities to Aternity. Most components are mandatory, but you can choose to add or omit some of the optional components and their associated functionality. Learn more about Aternity Docker Components Server.

For security reasons, it always better to set up servers as a non-root user with restricted privileges to run only certain predefined commands.

Sudoers is the configuration file that provides the list of commands and access permissions. It defines who can do what. Only if the file permits the user access, the system invokes the requested command. The access permissions include enabling only the listed commands and only from the specified servers; requiring a password per user or group; or never requiring a password at all for a particular command line. ALL is a special value in the sudoers file meaning “no restrictions.”

To set up servers as root user, the user must also be predefined in the sudoers file.

Before you begin

  • Download the latest Aternity on-premise's main setup package from the Aternity Support Site by selecting Software (size) (learn more).

  • The Docker Components setup package (aternity-docker-components-<version>.tgz file) is part of the main setup package.

  • Tip

    The Docker setup files must remain on the Linux host machine as an administrative tool, so location should be a permanent location with a sufficient disk space for the tool (about 8 GB).

  • Be sure to read Upgrade to Aternity on-premise 11.0.3. Update Aternity in the correct order. Make sure you already updated those servers that precede the current upgrade.

  • Check that the Docker Components server conforms to the minimum system requirements:

    Attribute Requirement

    Hardware

    Hardware specifications depend on the size of your Aternity on-premise deployment. Choose the sizing and hardware specifications for your deployment size.

    Network

    Ensure this server has a static IP v4 address, and that you open the required ports.

    Operating system for Aternity Docker Components Server

    • Linux CentOS 7.4 or 7.5 or 7.6 or 7.7. To verify your version of CentOS, enter cat /etc/centos-release

    • Red Hat Enterprise Linux (RHEL) 7.4 or 7.5 or 7.6 or 7.7. To verify the RHEL version, enter cat /etc/redhat-release

    Docker version for Aternity Docker Components Server

    Aternity does not supply the Docker engine. Customers are responsible for its installation. It is required for the Aternity Docker Components Server, regardless of operating system.

    • On CentOS, Aternity supports Docker for CentOS 17.x or 18.x. Learn more. Use either the Community Edition (CE) or the Enterprise Edition (EE). EE requires subscription, while CE is free.

    • On Red Hat Enterprise Linux (RHEL), Aternity supports Docker 1.13, 17.x, and 18.x, but only 1.13 version is free. RHEL Docker 17.x and 18.x (Enterprise Edition) are only available for RHEL with a paid subscription to Docker.

    • After you set up the Docker engine and run it, you can set up the Docker Components from a Docker image file.

    If you do not have an internet access, follow the procedure explained here. You can always go to the Docker website to learn more.

    Partitions

    20-25 GB of free disk space must be available on the partition with the Docker engine’s local storage (by default, located at /var/lib/docker/).

    Divide free disk space into several partitions where each partition is dedicated to the data directory of a different component: Messaging Broker(Kafka), and Raw Data Component (Cassandra). Allocate disk space to each partition according to hardware requirements of the relevant sizing model. The rest free disk space is dedicated to log files and REST APIs. Learn more.

    Setup Permissions

    Only users who are defined in the sudoers file can run the setup. Start as a non-root user and follow the setup procedure. At some point, you will be prompted to ask your IT representative to define permissions in the sudoers file. It is possible to run the setup as root user on the computer if this user is defined in the sudoers file as well.

    If you run the setup as a user that requires a password, setup will prompt you for the password. If the user does not require a password, the setup does not interrupt the process with those prompts.

    Email server

    Verify the Aternity Management Server is configured to work with an email server. Learn more.

Procedure

  1. Step 1 Access the Docker Components computer and log in.

    Log in to the Aternity Docker Components Server as a user configured to run Docker Components as a non-root user. Learn more.

  2. Step 2 Stop the services.

    In the aternity-docker-admin home directory, run the command ./aternity-docker-admin stop. This stops all Docker components.

  3. Step 3 Locate the folder where the .tgz and the aternity-docker-components files reside and rename them for backup purposes. You might need them later.
  4. Step 4 Locate the new Docker Components setup package, aternity-docker-components.tgz which you downloaded as part of the Aternity on-premise 11.0.3 setup package.
    Copy it to a permanent destination folder on this computer, and ensure to keep it there.
  5. Step 5 Extract the contents of the .tgz file by entering:
    tar -xvf aternity-docker-components-<version>.tgz
    Field Description
    -x

    Use -x to unzip the contents of the package.

    -v

    Use -v to output all messages (verbose).

    -f

    Use -f to specify the filename.

    Once extracted, the .tgz file created in the same location a new directory called aternity-docker-components with all the files and folders described in the below table.

    Important

    Make sure to place the aternity-docker-components in a dedicated directory, for example \docker, and NOT inside any of the data or logs directories of other components (/data/cassandra, /data/kafka, /data/rest_api, or /data/logs). If it is located in any of those default locations, it may harm the component operation.

    The downloaded package contains a number of files and folders, including:

    File/Folder Description

    aternity-docker-admin

    This script sets up a single Aternity Docker Components Server. In addition, it can also run different commands. Do not edit this file.

    properties.ini

    This file contains the properties used by the setup script. You must edit this file before running the setup, so that the script will know how and where to set up the Aternity Docker Components Server.

    It is possible to edit network ports thru which different components communicate with each other in this file. If you changed the default ports in older v11.x, locate the old file you backed up and get the list of ports from that file. Make sure these ports are open on relevant servers.

    versions.ini

    This file contains the version identifiers of all Docker Components.

    templates

    The folder that contains the sudoers file. The configuration file sudoers provides detailed access permissions, including
    • allowing only certain user(s) to run docker commands

    • allowing to run only the specified limited list of commands

    • enabling commands only from the predefined servers

    • requiring a password per user or group; requiring re-entry of a password every time or never requiring a password at all for a particular command line

    Utilities

    This folder contains all possible commands that you can carry out using the tool.

  6. Step 6 In the folder aternity-docker-components open the templates folder.
  7. Step 7 Supply your IT representative with sudoers.template file.
  8. Step 8 (IT people only) Grant access permissions in the sudoers file allowing privileged user(s) to set up and administer Docker Components server. Learn more.
  9. Step 9 Get the file back with the defined privileges for user(s) who are allowed to set up and administer Aternity Docker Components server and continue with the server setup.
  10. Step 10 Edit the properties.ini
    Edit the setup parameters in the properties.ini file
    Parameter Description

    installation_size in the [General] section.

    Enter the size of your Aternity deployment:

    Learn more.

    management_url in the [General] section.

    Enter the Aternity Management Server hostname or FQDN (recommended) or IP v4 address, including protocol prefix. For example, https://aternity.mycompany.com.

    FQDN in the [General] section.

    Specify a fully qualified domain name for the Docker Components host. If empty, the hostname of the Docker Components host will be used.

    logs_dir

    in the [General] section.

    Define the directory for the log files location (absolute path).

    aternity_containers_user

    Define the runtime user who will run the setup and other administration commands (this user replaces the root privileged user).

    It can be any Linux user account name that already exists on the host.

    It is possible to run the setup as root user on the computer if this user is defined in the sudoers file as well.

    port in the [agent_management] section.

    Displays the default communication port.

    You can change the port, if necessary.

    Make sure the port is open at the firewall and it is unique for each component.

    data_dir in the [cassandra] section.

    Define the directory for the Raw Data Component files (absolute path), for example data_dir = /data/cassandra.

    port in the [cassandra] section.

    Displays the default communication port.

    You can change the port, if necessary. If you changed the default in the previous version, locate the old properties.ini file that you renamed in step 3 and enter the same port.

    Make sure the port is open at the firewall and it is unique for each component.

    port in the [housekeeper] section.

    Displays the default communication port.

    You can change the port, if necessary. If you changed the default in the previous version, locate the old properties.ini file that you renamed in step 3 and enter the same port.

    Make sure the port is open at the firewall and it is unique for each component.

    data_dir in the [kafka] section.

    Define the directory for the Messaging Broker files (absolute path), for example data_dir = /data/kafka.

    port in the [kafka] section.

    port in the [zookeeper] section.

    deploy in the [portal_ds] section.

    (Optional) Enter yes to deploy the Aternity Data Source for Portal.

    Enter no if you do not use this optional component. The component will not be installed.

    port in the [portal_ds] section.

    external_url in the [portal_ds] section.

    If no value is given, then the FQDN will be used. If no value was given for the FQDN either, then the hostname will be used. Additionally, define the external URL to the Aternity Data Source for Portal if a load balancer or proxy are to be used, and user requests will be made to an address other than that of the Docker Components host.

    deploy in the [rest_api] section.

    (Optional) Enter yes to deploy REST API.

    Enter no if you do not use this optional component. The component will not be installed.

    port in the [rest_api] section.

    data_dir in the [rest_api] section.

    Define the directory for the Aternity REST API Server files (absolute path).

    external_url in the [rest_api] section.

    If no value is given, then the FQDN will be used. If no value was given for the FQDN either, then the hostname will be used. Additionally, define the external URL to the Aternity REST API Server if a load balancer or proxy are to be used, and user requests will be made to an address other than that of the Docker Components host.

    deploy in the [SDA] section.

    (Optional) Enter yes to deploy the SDA Server (Service Desk Alerts).

    Enter no if you do not use this optional component. The component will not be installed.

    port in the [SDA_engine] section.

    port in the SDA [Notification_sender] section.

    keystore in the [ssl] section.

    (Optional) Path to the keystore.

    Provide an absolute path to the keystore that holds the SSL certificate (typically a .jks file). Save the file in a permanent location on the Aternity Docker Components Server.

    The keystore is used to secure the Aternity REST API Server, Aternity Data Source for Portal, Raw Data Component, and Messaging Broker and must contain the appropriate certificate(s) for that. Providing a path to the keystore automatically sets the Aternity REST API Server and Aternity Data Source for Portal to work with HTTPS (SSL).

    Learn more

    keystore_password in the [ssl] section.

    (Optional) Password used to access the keystore.

    Learn more

    key_alias in the [ssl] section.

    (Optional) Alias that identifies the key in the keystore.

    key-password in the [ssl] section.

    (Optional) Password used to access the key in the keystore.

    cassandra_certificate_file in the [ssl] section.

    Provide the path to a .pem file that contains a certificate (no key), and is used to secure (SSL) connection to the Raw Data Component.

    truststore in the [ssl] section.

    (Optional) Truststore that holds SSL certificates.

    Provide an absolute path to the truststore file. Save the file in a permanent location on the Aternity Docker Components Server.

    Learn more

    truststore_password in the [ssl] section.

    (Optional) Password used to access the truststore.

    Learn more

    Note

    The setup creates the directories while running.

  11. Step 11 Once you defined all the parameters, save the properties.ini file.
  12. Step 12 (Optional) To verify that all prerequisites are properly installed, run the command ./aternity-docker-admin verify-prerequisites
    Setup verifies prerequisites
    Note that this command will automatically run during the installation, even you you skip the manual step.
  13. Step 13 (Optional) To verify that the Docker Components server can access other Aternity servers in your deployment, run the command ./aternity-docker-admin verify-external-server-access
    Setup verifies the access to other servers
    Note that this command will automatically run during the installation, even you skip the manual step.
  14. Step 14 Navigate to the installer folder and run the installation command: ./aternity-docker-admin install

    This may take several minutes to complete. Wait for the setup to complete, with the status 100%.

    Check the status of the installation and wait until it completes
  15. Step 15 To verify that all components are up and running, view their status by entering the command ./aternity-docker-admin status

    It may take up to 30 seconds.

    Note

    (For Aternity 11.0.2) Running a lot of docker containers may cause high memory consumption of Linux NetworkManager. Thus, Aternity recommends to disable NetworkManager service on the Docker Components machine (run as a privileged OS user systemctl mask NetworkManager).

  16. Step 16 To troubleshoot and verify the state of the components, open in Aternity the System Health dashboard by going to the Gear Icon > Tools > Settings > System Health. Learn more.
  17. Step 17 To troubleshoot, stop all or some components by entering the command ./aternity-docker-admin stop or ./aternity-docker-admin stop <component name>
    Note

    Use additional commands of the Docker administration tool for troubleshooting and security deployment. You can see the full list of available commands and their usage by entering the command ./aternity-docker-admin --help

    Command Usage Description

    start

    ./aternity-docker-admin start

    ./aternity-docker-admin start <component name>

    Starts all components or only the one you specify.

    stop

    ./aternity-docker-admin stop

    ./aternity-docker-admin stop <component name>

    Stops all components or only the one you specify.

    status

    ./aternity-docker-admin status

    Shows the status for all components.

    restart

    ./aternity-docker-admin restart

    ./aternity-docker-admin restart <component name>

    Restarts all components or only the one you specify.

    properties [Show] or [Reset]

    ./aternity-docker-admin properties show

    ./aternity-docker-admin properties reset

    Shows the properties of the installed components.

    Resets the properties of the installed components.

  18. Step 18 To secure access to the Docker Components, see Secure Aternity Management Server with SSL Encryption (HTTPS).
  19. Step 19 (Optional) To set passwords for the Docker Components, specifically for Raw Data Component, see Update Passwords in your Aternity Deployment.