Install ADCM

Daria Barysheva

ADCM requires a separate host. Before installing ADCM, we recommend to read its documentation.

The installation steps are listed below.

Step 1. Check prerequisites

Software and hardware requirements

ADCM is a software that is distributed in the form of a Docker image. To install it, you need:

  • One of the following operating systems:

    Ubuntu

    • Ubuntu 22.04 LTS

    CentOS

    • CentOS 7.9

    RHEL

    • RHEL 7.9

    • RHEL 9

    ALT Linux

    • ALT Linux 8.4 SP

    • ALT Linux 10.2 SP

    Astra Linux SE

    • Astra Linux SE 1.7.6 Orel

    • Astra Linux SE 1.8.4 Orel

    • Astra Linux SE 1.8.6 Orel

    • Astra Linux SE 1.7.6 Voronezh

    • Astra Linux SE 1.8.4 Voronezh

    • Astra Linux SE 1.8.6 Voronezh

    RED OS

    • RED OS 7.3 Certified edition

    • RED OS 8.0 Certified edition

  • A user account with sudo privileges.

  • Access to the official repositories of CentOS Extras and CentOS Base. These repositories are available in the operating system by default. However, if they were disabled, you need to enable them before proceeding (for example, by editing the repository configuration file in the /etc/yum.repos.d/ directory).

  • The software package installer YUM/APT.

  • The hardware that meets the following conditions:

    IMPORTANT

    The following system requirements are minimal. The target sizing should be calculated based on the customer requirements.

    • CPU: 4 CPU cores;

    • RAM: 16 GB;

    • HDD: 50 GB.

IMPORTANT
Starting with ADCM 2.7.0, any Container Registry Client with downloaded images of ADPG, ADCM, and ADCM Installer will be required to install ADPG without the Internet connection and use it as the ADCM database. The installation is done via the ADCM Installer by specifying the URL of the local storage of the ADCM and ADPG images.

To grant the user the necessary rights to install ADCM, perform the steps described below.

Grant the root privileges for the user:

  • CentOS 7.9/RHEL 7.9/RED OS 7.3/ALT Linux 8.4 SP

  • Ubuntu 22.04 LTS/Astra Linux SE 1.7.6 Orel

$ sudo usermod -aG wheel <user>

where <user> is a username.

$ sudo usermod -aG sudo <user>

where <user> is a username.

Make sure that the /etc/sudoers file contains the record specified below depending on the operating system with the following command:

$ sudo vi /etc/sudoers

To return to the command line, press Esc, type :q!, and press Enter.

  • CentOS 7.9/RHEL 7.9/RED OS 7.3

  • Ubuntu 22.04 LTS/Astra Linux SE 1.7.6 Orel

  • ALT Linux 8.4 SP

## Allows people in group wheel to run all commands
%wheel  ALL=(ALL)       ALL
# Allow members of group sudo to execute any command
%sudo   ALL=(ALL:ALL) ALL
## Uncomment to allow members of group wheel to execute any command
WHEEL_USERS ALL=(ALL:ALL) ALL

Install Docker

CAUTION

Do not install Docker from the official Docker site. Instead, use the official repositories of your Linux distribution. The repositories provided by operating system developers tend to be more stable and secure.

Below are the step-by-step procedures of Docker installation on the examples of several operating systems supported by ADCM. These steps may differ for operating system versions other than those specified on tabs.

  • CentOS 7.9/RHEL 7.9

  • Ubuntu 22.04 LTS

  • ALT Linux 8.4 SP

  • Astra Linux SE 1.7.6 Orel

  • RED OS 7.3

  1. Using root privileges, update all packages that are currently installed in your system:

    $ sudo yum update -y

  2. Install the packages required for Docker installation and usage:

    $ sudo yum install -y yum-utils docker device-mapper-persistent-data lvm2

    where:

    • yum-utils is the package that provides the yum-config-manager utility;

    • device-mapper-persistent-data and lvm2 are packages required by the devicemapper storage driver.

  3. Start Docker:

    $ sudo systemctl start docker

  4. Enable Docker as a system service:

    $ sudo systemctl enable docker

  1. Update the package index:

    $ sudo apt-get update

  2. Install the packages required for Docker installation and usage:

    $ sudo apt-get install ca-certificates curl

    where:

    • ca-certificates is the package of Root CA certificates;

    • curl is the package for working with web resources.

    Confirm the use of additional disk space during the execution of the command.

  3. Add the official GPG key for the Docker repository:

    $ sudo install -m 0755 -d /etc/apt/keyrings
$ sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
$ sudo chmod a+r /etc/apt/keyrings/docker.asc

  4. Add the Docker repository:

    $ echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "jammy") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

  5. Update the package index:

    $ sudo apt-get update

  6. Install Docker Engine:

    $ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

    Confirm the use of additional disk space during the execution of the command.

  7. Start Docker:

    $ sudo systemctl start docker

  8. Enable Docker as a system service:

    $ sudo systemctl enable docker

  1. Update the package index:

    $ sudo apt-get update

  2. Install Docker Engine:

    $ sudo apt-get install docker-engine

    Confirm the use of additional disk space during the execution of the command.

  3. Start and enable Docker as a system service:

    $ sudo systemctl enable --now docker

  1. Update the package index:

    $ sudo apt-get update

  2. Install Docker Engine from the operating system repository:

    $ sudo apt-get install docker.io

    Confirm the use of additional disk space during the execution of the command.

  3. Start Docker:

    $ sudo systemctl start docker

  4. Enable Docker as a system service:

    $ sudo systemctl enable docker

  1. Install Docker Engine:

    $ sudo dnf install docker-ce docker-ce-cli

    Confirm the use of additional disk space during the execution of the command.

  2. Start and enable Docker as a system service:

    $ sudo systemctl enable docker --now

Disable SELinux

NOTE
It is recommended to disable SELinux only if CentOS 7.9 or RHEL 7.9 is used.

To disable SELinux permanently, set SELINUX=disabled in the /etc/selinux/config file, and reboot your system.

You can edit the file via the vi or vim command:

$ sudo vi /etc/selinux/config

The content of the changed file should look like this:

# This file controls the state of SELinux on the system.
# SELINUX= can take one of these three values:
#       enforcing - SELinux security policy is enforced.
#       permissive - SELinux prints warnings instead of enforcing.
#       disabled - SELinux is fully disabled.
SELINUX=disabled
# SELINUXTYPE= type of policy in use. Possible values are:
#       targeted - Only targeted network daemons are protected.
#       strict - Full SELinux protection.
SELINUXTYPE=targeted

You can also disable SELinux temporarily via the following command:

$ sudo setenforce 0

Still, it is strongly recommended to disable SELinux permanently, so that it does not restart on each system reboot.

CAUTION

Do not forget to reboot your host after SELinux is disabled.

Stop firewalld

If you use the firewalld service, stop it before installing ADCM.

Before stopping firewalld, make sure that it is installed, started, and enabled:

$ sudo systemctl status firewalld

The example of the command execution result:

● firewalld.service - firewalld - dynamic firewall daemon
   Loaded: loaded (/usr/lib/systemd/system/firewalld.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2024-12-02 10:02:57 UTC; 3min 25s ago
     Docs: man:firewalld(1)
 Main PID: 3023 (firewalld)
    Tasks: 2
   Memory: 22.8M
   CGroup: /system.slice/firewalld.service
           └─3023 /usr/bin/python2 -Es /usr/sbin/firewalld --nofork --nopid

Stop firewalld:

$ sudo systemctl stop firewalld

As an alternative, you can disable the firewalld service, so that it will not apply rules to network packets:

$ sudo systemctl disable firewalld

Allow access to the Docker CLI without root privileges

If in the future you want to access the Docker CLI without using root privileges, you should create a docker user group (if it does not exist) and add the current user to this group with the certain rights:

$ sudo groupadd docker
$ sudo usermod -a -G docker $USER

After running these commands, you should re-login under the current user.

Step 2. Install ADCM

Offline ADCM installation includes the following steps:

  1. Get an archive with the sh.xz extension that contains a special installation shell script from the Arenadata support team.

  2. Create a directory on the host where ADCM should be deployed, and put the received archive into it.

  3. Unpack the archive into the created directory using any of the available methods.

    NOTE
    Running the command can take some time. Please wait until it is completed.

  4. Load the Docker image to the local storage using the received script:

    $ sudo bash <script_name> unpack_adcm

    where <script_name> is the full script name with the extension (for example, adcm_2.5.0.sh).

    The example of a successful command execution result:

    Loaded image: hub.arenadata.io/adcm/adcm:2.5.0

  5. Create and start a new container based on the downloaded image. For data storage, you can use a named volume or a bind mount (for example, if you plan to configure logging, log rotation, or HTTPS):

    IMPORTANT
    The chosen data storage method must remain unchanged during future ADCM updates. Changing the storage method without prior backup and restore will cause data loss.

    • Named volume:

      $ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v adcm-data:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

    • Bind mount:

      NOTE

      When using a bind mount (for example, the host directory /opt/adcm), make sure that the directory is created and owned by 10001:10001 before starting the container:

      $ sudo mkdir -p /opt/adcm && sudo chown -R 10001:10001 /opt/adcm
      		 
      $ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v /opt/adcm:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

Step 3. Start ADCM

ADCM is just a container operated by Docker. So you are able to use simple Docker commands to start and stop ADCM:

  • To stop ADCM, use the following command.

    $ sudo docker stop adcm

  • To start ADCM, use the following command.

    $ sudo docker start adcm

  • In order to provide the automatic start of the Docker container after unexpected errors, use the following command.

    $ sudo docker update --restart=on-failure adcm
NOTE

  • For more information about Docker restart policies, refer to the Docker documentation.

  • If you allowed your user to access the Docker CLI without root privileges, then you can omit the sudo keyword from the commands listed above.
Container startup process

After the ADCM container starts, the following actions are performed:

  1. The required environment variables are checked.

  2. Secrets are initialized if they do not already exist.

  3. The compatibility of the installed bundles is checked against the contract versions of the current ADCM version.

  4. The required database migrations are applied.

  5. The components of the ADCM core container are started:

    • Backend Server;

    • Status Server;

    • Nginx.

Step 4. Check installation

Check the Docker container status

To make sure that the Docker container adcm is successfully deployed, run the following command:

$ sudo docker container ls

The example of the command execution result is listed below. Make sure that the STATUS value is equal to Up.

CONTAINER ID        IMAGE                               COMMAND             CREATED             STATUS              PORTS                    NAMES
74b5628146e5        hub.arenadata.io/adcm/adcm:2.0   "/etc/startup.sh"   4 days ago          Up 21 minutes       0.0.0.0:8000->8000/tcp   adcm

Check the 8000 port availability

After ADCM is installed and started, its web interface should become available on the 8000 port of the deployed container.

For Ubuntu 22.04 LTS, first install the packages required for executing the netstat command:

$ sudo apt-get install net-tools

You can check the 8000 port availability using these commands:

  • The netstat command — to display information about port listening.

    $ sudo netstat -ntpl | grep 8000

    The example of the command execution result:

    tcp6       0      0 :::8000                 :::*                    LISTEN                                             1514/docker-proxy-c

  • The curl command — to check the URL connection.

    $ curl http://localhost:8000

    The example of the command execution result:

    <!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Arenadata Cluster Manager</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="assets/favicon.ico">
<link rel="stylesheet" href="styles.10db6328264e0907c52f.css"></head>
<body>
  <app-root></app-root>
<script src="runtime-es2015.7eb406ed18bf0258cd35.js" type="module"></script><script src="runtime-es5.7eb406ed18bf0258cd35.js" nomodule defer></script><script src="polyfills-es5.2e224d70daec4412d3c2.js" nomodule defer></script><script src="polyfills-es2015.37e0553ac06970d6a5b5.js" type="module"></script><script src="main-es2015.39851da0ebf9ed6fec45.js" type="module"></script><script src="main-es5.39851da0ebf9ed6fec45.js" nomodule defer></script></body>
</html>

Check the ADCM web-interface

To log in to ADCM, use the user with administrator rights that is created by default:

  • User: admin

  • Password: admin

Log in to ADCM
Log in to ADCM

Later you can change the password if necessary. To do this:

  1. Open the user profile in the left navigation menu.

  2. Enter the current password in the Current password field.

  3. Fill in the New password field.

  4. Confirm a new password in the Confirm password field.

  5. Click Save.

    Change the admin password
    Change the admin password

Set the ADCM URL

For successful communication between ADCM and product clusters deployed via ADCM, it is important to correctly define the external ADCM address. This address is used by cluster components for sending information about their state to ADCM. To specify the ADCM URL, use the environment variable DEFAULT_ADCM_URL when creating the ADCM container. If you did not specify that variable, you should manually install the URL in the ADCM web interface. To do this, follow the steps:

  1. Select the Settings item in the left navigation menu.

  2. Expand the Global Options node in the tree of configuration settings.

    The Settings page
    The Settings page

  3. Enter the required value directly into the ADCM’s URL text field.

  4. Click Save to apply changes.

    Save the ADCM URL
    Save the ADCM URL

Step 5. Upgrade ADCM

CAUTION

General recommendations and limitations

  • Before upgrading, it is strongly recommended to back up ADCM data. For more information, see Backup and restore.

  • Downgrade of the ADCM version is not supported.

  • It is not recommended to update ADCM more than 5 minor versions ahead (see <minor> in the versioning format below).

  • Before upgrading ADCM to version 2.7.0, migrate data from SQLite to PostgreSQL. Migration can be performed in any ADCM version up to and including 2.6.0.

Version restrictions during upgrade

  • Version 2.10.0 is mandatory for installation and cannot be skipped. Direct upgrade from versions lower than 2.10.0 to 2.11.0 and later is not supported.

  • If installed clusters contain products with an outdated contract version, a warning about unsupported contract versions is displayed in the Docker container logs.

  • If installed clusters contain products with an unsupported contract version, the Docker container startup is stopped. Such products should be updated to a supported version.
IMPORTANT

ADCM 3.0.0 is required for installation and cannot be skipped during the upgrade.

Starting with ADCM 3.0.0, all processes inside the Docker container run as the unprivileged adcm user (UID/GID 10001) instead of the root user.

When upgrading without using ADCM Installer from an ADCM version earlier than 3.0.0, change the ownership of the /adcm/data directory before starting the container with the new ADCM version for the first time. Otherwise, the Docker container will not be able to access the existing data and will terminate.

If data is stored in a Docker volume, perform the following steps:

  1. Determine the name of the Docker volume mounted at the /adcm/data directory:

    $ sudo docker inspect \
    --format='{{range .Mounts}}{{if eq .Type "volume"}}{{.Name}}{{"\n"}}{{end}}{{end}}' \
    adcm

    The command returns the name of the Docker volume. Use this name instead of <volume_name> in the next command.

  2. Change the ownership of the data directory:

    $ sudo docker run --rm \
    -v <volume_name>:/adcm/data \
    --user 0:0 \
    --entrypoint sh \
    hub.arenadata.io/adcm/adcm:<version> \
    -c 'chown -R 10001:10001 /adcm/data'

    where <version> is the ADCM version to which you want to upgrade.

The ADCM update process depends on the installation method of ADCM.

Upgrade using ADCM Installer

If ADCM was deployed using ADCM Installer, the update is performed by modifying the configuration and applying the changes using the adi utility.

To update ADCM to the required version, follow these steps:

  1. Open the adcm.yaml configuration file used during installation. The configuration file example is provided in the Use ADCM Installer article.

  2. In the section corresponding to ADCM, specify the Docker image of ADCM with the required version tag in the image parameter, for example, hub.arenadata.io/adcm/adcm:2.12.0.

  3. Apply the changes:

    $ sudo adi apply

    After the command is executed, the ADCM container will be recreated using the image specified in the image parameter of the adcm.yaml file.

Online upgrade

If you need to upgrade the previously installed version of ADCM that was installed without using ADCM Installer, do the following:

  1. Stop and remove the adcm container:

    $ sudo docker rm -f adcm

  2. Download the required Docker image from the Arenadata Docker Registry:

    $ sudo docker pull hub.arenadata.io/adcm/adcm:<version>

    where <version> is the desired ADCM image version in one of the following formats:

    • <major>.<minor>.<patch> — if you need a specific ADCM patch. For example, 2.0.0.

    • <major>.<minor> — if you need the last patch within the selected ADCM version. For example, 2.0.

    IMPORTANT

    • latest was used for earlier versions of ADCM and is no longer supported starting from version 2.0.0.

    • Before ADCM 2.0.0, the following format was used for versioning: YYYY.MM.DD.HH.

  3. Create and start a new Docker container based on the downloaded image, choosing the option depending on how the previous ADCM version was installed:

    IMPORTANT
    When upgrading ADCM, use the same data storage method (bind mount or named volume) as in the previous installation. Changing the storage method without prior backup and restore will cause data loss.

    • If a named volume was previously used:

      $ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v adcm-data:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

    • If a bind mount was previously used:

      NOTE

      Before starting the container, make sure that the existing data directory is owned by 10001:10001. If necessary, change the owner:

      $ sudo chown -R 10001:10001 /opt/adcm
      		 
      $ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v /opt/adcm:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>
    NOTE
    For more information on the environment variables (DB_HOST, DB_PORT, DB_USER, DB_NAME, DB_PASS, and DB_OPTIONS), see the Installation article.

Offline upgrade

You can also try offline ADCM update in situations without Internet access.

To upgrade ADCM that was installed without using ADCM Installer offline, follow these steps:

  1. Stop and remove the adcm container:

    $ sudo docker rm -f adcm
    NOTE
    For customers who use Enterprise editions of products, it is possible to contact the Arenadata support team to get an archive with the sh.xz extension that contains a special installation shell script. After stopping the adcm container, the ADCM update process includes the installation according to the instruction.

  2. Download the required Docker image from the Arenadata Docker Registry on a host that has Internet access:

    $ sudo docker pull hub.arenadata.io/adcm/adcm:<version>

    where <version> is the desired ADCM image version in one of the following formats:

    • <major>.<minor>.<patch> — if you need a specific ADCM patch. For example, 2.0.0.

    • <major>.<minor> — if you need the last patch within the selected ADCM version. For example, 2.0.

    IMPORTANT

    • latest was used for earlier versions of ADCM and is no longer supported starting from version 2.0.0.

    • Before ADCM 2.0.0, the following format was used for versioning: YYYY.MM.DD.HH.

  3. Save the Docker image to a .tar file:

    $ sudo docker save -o <file_name> hub.arenadata.io/adcm/adcm:<version>

    where <file_name> is the full name of the created file with the extension (for example, adcm_2.5.0_arenadata.tar).

    NOTE
    Running the command can take some time. Please wait until it is completed.

  4. Copy the saved file from the current host to a host without Internet connection using any available methods.

    IMPORTANT
    Make sure you have configured access to hosts and necessary file permissions.

  5. Load the Docker image from the .tar file:

    $ sudo docker load -i <file_path>

    where <file_path> is the absolute path to the .tar file with the Docker image.

    The example of a successful command execution result:

    Loaded image: hub.arenadata.io/adcm/adcm:2.5.0

  6. Create and start a new Docker container based on the downloaded image, choosing the option depending on how the previous ADCM version was installed:

    IMPORTANT
    When upgrading ADCM, use the same data storage method (bind mount or named volume) as in the previous installation. Changing the storage method without prior backup and restore will cause data loss.

    • If a named volume was previously used:

      $ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v adcm-data:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

    • If a bind mount was previously used:

      NOTE

      Before starting the container, make sure that the existing data directory is owned by 10001:10001. If necessary, change the owner:

      $ sudo chown -R 10001:10001 /opt/adcm
      		 
      $ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v /opt/adcm:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>
    NOTE
    For more information on the environment variables (DB_HOST, DB_PORT, DB_USER, DB_NAME, DB_PASS, and DB_OPTIONS), see the Installation article.
Found a mistake? Seleсt text and press Ctrl+Enter to report it