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:
-
Install Docker. For more information, refer to the Docker documentation.
-
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.
Parameter | Type | Description | Default value |
---|---|---|---|
ADCM database host |
string |
ADCM database server address. This parameter is ignored when specifying the |
— |
ADCM database port |
uint16 |
Port number for connecting to the ADCM database. This parameter is ignored when specifying the |
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
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, |
— |
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, |
— |
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, |
— |
ADCM volume name or path |
string |
Name of the ADCM container volume (in the above example — |
adcm |
ADCM image |
string |
ADCM container image repository (in the above example — |
hub.arenadata.io/adcm/adcm |
ADCM image tag |
string |
Docker image tag used for the ADCM container (in the above example — |
2.6.0 |
ADCM publish port |
uint16 |
Localhost port for the ADCM container (in the above example — |
8000 |
ADCM url |
uint16 |
URL of the host where the ADCM container is deployed. Use the following format: |
IP address of a host where the ADCM container is started and the ADCM port number specified in the |
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 — |
hub.arenadata.io/adcm/postgres |
ADPG image tag |
string |
Docker image tag used for the ADPG container (in the above example — |
v16.3.1 |
ADPG publish port |
uint16 |
Localhost port for the ADPG container (in the above example — |
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...
NOTEThe private key can also be passed via theAGE_KEY
variable, for example:export AGE_KEY=AGE-SECRET-KEY-1…
.
# 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:
-
Creating and running the
my-adcm-adpg-1
container. -
Creating the PostgreSQL database.
-
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.