Use ADCM Installer

ADCM Installer is a tool written in Go to help simplify the processes of installation, upgrade, and configuration of the ADCM installations. It also allows you to extend the Docker Compose functionality by secret storage.

ADCM Installer consists of the following packages:

  • Docker Compose — controls the life cycle of Docker containers.

  • age-encryption — encodes and decodes sensitive data (such as username and password to connect to the database).

For details of possible ADCM Installer use cases, see Use cases.

Quick start with ADCM Installer

NOTE
If you use CentOS, the operating system version must be at least version 8.

Follow the instructions below to install ADCM Installer:

  1. Install Docker. For more information, refer to the Docker documentation.

  2. Download the adi file to the /usr/local/bin directory and set permissions of the adi file as follows:

    $ sudo wget -O /usr/local/bin/adi https://github.com/arenadata/adcm-installer/releases/tag/<version>/adi
    $ sudo chmod +x /usr/local/bin/adi

    where <version> is the ADCM Installer version.

    Wait for the file download to finish.

To get a brief background on the ADCM Installer commands, use the following command:

$ adi --help

The expected command execution result:

Command line tool for installing Arenadata products

Usage:
  adcm-installer [flags]
  adcm-installer [command]

Available Commands:
  adcm-versions List versions of Arenadata products
  apply         Apply a configuration by file name
  completion    Generate the autocompletion script for the specified shell
  components    Manage installed components
  delete        Delete resources by file name or installation name
  help          Help about any command
  init          Initialize a new configuration
  list          List running ADCM installation
  secrets       Manage secrets

Flags:
  -h, --help      help for adcm-installer
      --version   Print the version and exit

Use cases

ADCM Installer supports the following commands:

  • init

  • apply

  • completion

  • list

  • adcm-versions

  • secrets

  • delete

The command descriptions and examples of their usage are given below.

Initialize a configuration file

The init command generates the configuration file described below, which is necessary for the ADCM installation deployment.

For example, to initialize the configuration file of ADCM using PostgreSQL as a database, use the following command with the --adpg flag:

$ adi init my-adcm --adpg

where my-adcm is the name of the ADCM installation that includes the Docker containers: my-adcm-adpg-1 and my-adcm-adcm-1.

To specify the database credentials and configure the database connection settings, use the interactive mode by specifying the -i or --interactive flag:

$ adi init my-adcm --adpg -i
NOTE
Without the --adpg flag, settings for connection to an external PostgreSQL database will be requested.

Parameters that can be specified in the interactive mode are described below.

Requested parameters
Parameter Type Description Default value

ADCM database host

string

ADCM database server address. This parameter is ignored when specifying the --adpg flag

 — 

ADCM database port

uint16

Port number for connecting to the ADCM database. This parameter is ignored when specifying the --adpg flag

5432

ADCM database name

string

Name of the ADCM database

adcm

ADCM database user

string

Username for connecting to the ADCM database

adcm

ADCM database password

string

Password for connecting to the ADCM database

 — 

Postgres SSL mode

string

Flag used to establish an SSL connection to the PostgreSQL database. This parameter is ignored when specifying the --adpg flag. Possible values:

  • disable

  • allow

  • prefer

  • require

  • verify ca

  • verify full

The description of each value is given in the Configure ADCM to use an external database article

 — 

ADCM database SSL CA file path

string

Absolute path to the file containing SSL certificate signed by certificate authority (CA) including the file name. This parameter is ignored if an SSL connection is not made, in other words, disable is selected as the value of the Postgres SSL mode parameter

 — 

ADCM database SSL certificate file path

string

Absolute path to the file of the client SSL certificate including the file name. This parameter is ignored if an SSL connection is not made, in other words, disable is selected as the value of the Postgres SSL mode parameter

 — 

ADCM database SSL private key file path

string

Absolute path to the secret key used for the client SSL certificate. This parameter is ignored if an SSL connection is not made, in other words, disable is selected as the value of the Postgres SSL mode parameter

 — 

ADCM volume name or path

string

Name of the ADCM container volume (in the above example — my-adcm-adcm-1) or full path to the directory containing the SQLite database files. This parameter is used for migration of the ADCM data from SQlite to PostgreSQL

adcm

ADCM image

string

ADCM container image repository (in the above example — my-adcm-adcm-1)

hub.arenadata.io/adcm/adcm

ADCM image tag

string

Docker image tag used for the ADCM container (in the above example — my-adcm-adcm-1)

2.6.0

ADCM publish port

uint16

Localhost port for the ADCM container (in the above example — my-adcm-adcm-1)

8000

ADCM url

uint16

URL of the host where the ADCM container is deployed. Use the following format: http://<ip_address>:<port>/

IP address of a host where the ADCM container is started and the ADCM port number specified in the ADCM publish port parameter

ADPG superuser password

string

Password of the superuser role which is set during the PostgreSQL database initialization

 — 

ADPG image

string

ADPG container image repository (in the above example — my-adcm-adpg-1)

hub.arenadata.io/adcm/postgres

ADPG image tag

string

Docker image tag used for the ADPG container (in the above example — my-adcm-adpg-1)

v16.3.1

ADPG publish port

uint16

Localhost port for the ADPG container (in the above example — my-adcm-adpg-1)

5432

If parameter values are not specified, default values will be used for names and Docker container configuration parameters and passwords will be generated automatically.

After the command mentioned above is executed, the following files will be created:

  • adcm.yaml (or adcm.yml) is the ADCM installation configuration file in the YAML format;

  • age.key is the file with the private key in the AGE-SECRET-KEY-1… format to access sensitive data (secrets) stored in the adcm.yaml (or adcm.yml) file.

To take advantage of additional command options, use the following flags:

  • --force — allows you to overwrite the existing configuration file;

  • -o or --output — allows you to save the configuration file with the given name, for example: --output /<file_path>, where <file_path> is the absolute path to the configuration file in the YAML format including the file name;

  • --from-config — allows you to specify the file that contains the values of parameters requested when using the interactive mode;

  • --age-key-file — determines the location of the file with the private key;

  • --age-key — determines the private key, for example:

    $ adi init my-adcm --age-key AGE-SECRET-KEY-1...
    NOTE
    The private key can also be passed via the AGE_KEY variable, for example: export AGE_KEY=AGE-SECRET-KEY-1…​.
The configuration file structure
# Project name
name: my-adcm
# Configurations of the following Docker containers: my-adcm-adcm-1 and my-adcm-adpg-1
services:
  adcm:
    # Add specified Linux capabilities to the Docker container. The list of supported capabilities is given in the Linux documentation
    cap_add:
      - CAP_CHOWN
      - CAP_SETUID
      - CAP_SETGID
    # Remove specified Linux capabilities from the Docker container
    cap_drop:
      - ALL
    # Order in which the Docker containers are started. In this case, the my-adcm-adcm-1 container will be started after the my-adcm-adpg-1 container startup
    depends_on:
      adpg:
        # Condition under which the my-adcm-adcm-1 container is started. In this case -- wait until the my-adcm-adpg-1 container is healthy
        condition: service_healthy
        restart: true
        required: true
    # Custom hostname for the Docker container
    hostname: my-adcm-adcm
    # Image name
    image: hub.arenadata.io/adcm/adcm:2.5.0
    # Metadata to add to the Docker container
    labels:
      app.arenadata.io/type: adcm
    # Create a dedicated network for the Docker container on the host
    networks:
      default: null
    # Map ports between the Docker container and the host
    ports:
      - mode: ingress
        # Port of the Docker container
        target: 8000
        # Published port
        published: "8000"
        # Port protocol
        protocol: tcp
    # Pull the Docker image from the registry for every container startup
    pull_policy: always
    # Policy of the Docker container restart. In this case, the policy restarts the Docker container in all cases, except forcible stop of the Docker container
    restart: unless-stopped
    # Provide the Docker container with access to sensitive data defined by the x-secrets top-level element
    secrets:
      - source: adcm-db-name
        target: /run/secrets/adcm-db-name
      - source: adcm-db-user
        target: /run/secrets/adcm-db-user
      - source: adcm-db-pass
        target: /run/secrets/adcm-db-pass
    # Named volumes that are accessible by the Docker container
    volumes:
      - type: volume
        source: my-adcm-adcm
        target: /adcm/data
        volume: {}
  adpg:
    cap_drop:
      - ALL
    hostname: my-adcm-adpg
    # Docker container health check using the pg_isready utility
    healthcheck:
      test:
        - CMD-SHELL
        - pg-entrypoint isready postgres
      timeout: 3s
      interval: 10s
      retries: 3
    image: mybackspace/adpg:16.4
    labels:
      app.arenadata.io/type: adpg
    networks:
      default: null
    pull_policy: always
    # Run the Docker container with a read-only internal filesystem
    read_only: true
    restart: unless-stopped
    # Prevent the Docker container processes from gaining additional privileges
    security_opt:
      - no-new-privileges
    # User used to run the Docker container
    user: 10001:10001
    volumes:
      - type: volume
        source: my-adcm-adpg
        target: /data
        volume: {}
# Named network that allows Docker containers to communicate with each other
networks:
  default:
    name: my-adcm_default
# Named volumes that will be created with the Docker container initial startup
volumes:
  my-adcm-adcm:
    name: my-adcm-adcm
  my-adcm-adpg:
    name: my-adcm-adpg
# Sensitive data that is granted to the Docker containers
x-secrets:
  age_recipient: age1htxwzyy75rlrhut6jry0uet3ks7cw44w80jl2gktukp9m800auyqspyfws
  data:
    adcm-db-name: YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBoMWh2d2E5TU8xR0RkQVdCalB6ZUEvZUh5d2ZqN3hpbEJBK2taMHZCM3hvCkNzbVNudHlSVUIxY0hCT3lDaHJNVld0VHlHK1hRU2RjMzRnUGxjaUdBUDAKLS0tIEFIcmVEVnpQVE5iVFdwQ0NRcVpNQ0w5TWRRQTB3ZmZBemZVbFcySk5ZOEEK3Y7P8Lgl0+Gx9+UwJQOzRheRbVxox/XaXEj6M1xMukn56AgJ
    adcm-db-pass: YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBWRXR6eEduL3piZk1oODd5QnNENUZPTHhzMXhxczRMNTVhd0VrUWJoYlNVCnV5OHBadTlpMlpTWnc4SXFoMThqbHE4UVBheVloNnk1U0o1N2E2dHZaZFEKLS0tIFViUm96eXJFWWJJY3o1WHlNYmdneVRQUTVRL3ZKbFlhVFF2Z2l4cDZ0QUUKr7EYAMlS/h6TeoZV4bgBKqlVDUysOKGgAU1qWjCOezUWA/2hARb1Kt928jB+Qn8i
    adcm-db-user: YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSAzYm95bDZDV1NrbGpuYWdXN21IaUZwSFVaSHlVNVZXd2tGR1RhWE1XcTFjCnY0RUFJQnZwcUxWWk40bjUxWi9xdHM3TFpOUTZlYWk0elpSU21mUnlTbWcKLS0tIHJvYjZHNGk4UUNDMnFCd3NFVGsvV0tyYWprQUw2Wm1pMGNHMWRYYkIwTlEK4pYnqi8iDd2GefTUK2SLz8Q3BO5Re4DHmV33+TKiUQcjTXV6
    adpg-password: YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBObFI3MUptcW1ZdSs0ZGc2Tlp3SXprRGptdWhld01RekxjakZNQ1NIWFZNCnZDbzYzUXVzNUtvS3dYbkxhNnNNV2k2TXJCZWNQeVI2Y2c0aXlKdjk0bUUKLS0tIDZEUWFNRGRScFN0Y2s5WUQwMzUzQTJKNTAzRTBmVXhWNFQ0V2tXZUN6S00KTA1a/+YkjQ1bzr4/9I5GTHAnFHgCwblCW656C8O2qyw2NmbZtgeypIWf6n1yz2wg

Deploy the ADCM installation

The apply command allows you to deploy the ADCM installation with the created files adcm.yaml (or adcm.yml), and age.key.

$ sudo adi apply

When you run the command, the docker-compose.yaml file is generated which participates in the following actions:

  1. Creating and running the my-adcm-adpg-1 container.

  2. Creating the PostgreSQL database.

  3. Creating and running the my-adcm-adcm-1 container.

To ensure that the ADCM installation is deployed successfully, run the commands described in the Installation article.

To deploy the ADCM installation in debug mode, specify the --dry-run flag. As a result, the docker-compose.yaml file is created without creating and running containers.

For more information on other flags that can be specified when running the apply command, use the following command:

$ adi apply --help
NOTE
With the --help flag, you can also get a brief description of other commands described below.

Create scripts with auto-complete

The completion command allows you to generate scripts with auto-complete for the ADCM Installer commands using the Tab key for the following shells:

  • Bash

  • fish

  • PowerShell

  • Zsh

NOTE
For Bash, first install the bash-completion package required for the script.

For more detailed instructions on how to use a generated script, run the following command:

$ adi completion <shell> --help

where <shell> is the shell name.

List running ADCM installations

The list command allows you to obtain the following information on the ADCM installations:

  • NAMES — the ADCM installation name;

  • STATUS — the status and the number of the Docker containers;

  • CONFIG FILES — the path to the configuration file.

Command example:

$ sudo adi list

The example of the command execution result:

NAMES               STATUS              CONFIG FILES
my-adcm             running(3)          /home/adelya/adcm-installer/adcm.yaml

To display information on stopped ADCM installations, specify the --all flag.

List available ADCM versions

The adcm-versions command allows you to check for the new ADCM image versions available for download from Arenadata Docker Registry:

$ adi adcm-versions --all

The example of the command execution result:

2.5.1
2.5.0
2.4.0
2.3.0
2.2.0
2.1.2
2.1.1
2.1.0
2.0.0

To display the last five versions, run the adcm-versions command without specifying the --all flag.

Manage secrets

The secrets command allows you to manage secrets specified in the configuration file as follows:

  • secrets new-key — creates a new private key which by default is saved in the age.key file;

  • secrets show — shows secrets defined during initialization;

  • secrets set — determines new secret values, for example:

    $ adi secrets set adcm-db-pass 1234

Stop and remove running ADCM installations

The delete command stops running ADCM installations using the specified configuration file or running installation name.

If adcm.yaml (or adcm.yml) or age.key are located in the directory in which the command is run, the delete command will be executed automatically without specifying the configuration file or the ADCM installation name:

$ sudo adi delete

As a result, the ADCM installation will be stopped with the preservation of data specified during initialization of the configuration file.

To remove a running ADCM installation along with volumes related to the installation, specify the --volumes flag. Confirm the removal during the execution of the command.

Found a mistake? Seleсt text and press Ctrl+Enter to report it