Installation using Docker

Install and run Axiomatics Services Manager (ASM) using a Docker container package.

note

The instructions below refer to a fresh installation of ASM. In case you already have ASM installed in your system, read how to upgrade.

Requirements

The following third-party software must be installed before installing ASM.

Docker Desktop

• Docker Engine
• Docker Compose

ASM 7.3 has been tested with Docker Engine 20.10.17 and Docker Compose 2.10.2.

Preparation

AWS CLI

Axiomatics Services Manager is downloaded via AWS CLI. If you have not already done so, install AWS CLI following the instructions in AWS documentation.

Download the file

The ASM distribution is downloaded as a ZIP file, containing a pre-configured Docker-based installation.

1. To have the appropriate access to Axiomatics' downloads, you need to configure the AWS CLI account with the aws configure command, as explained in AWS documentation. This step requires an Access key ID and a Secret access key, which will have been provided to you by Axiomatics.

2. After configuring the AWS CLI account, run the following command in the terminal:

   aws s3api get-object --bucket axiomatics-customer-artifacts --key releases/com/axiomatics/axiomatics-services-manager/axiomatics-services-manager/7.3.0-0/axiomatics-services-manager-7.3.0-0.zip axiomatics-services-manager-7.3.0-0.zip

This downloads the ASM distribution ZIP file to your computer.

Installation procedure

Install the application

1. Extract the ASM distribution ZIP file to the folder from where you want to run ASM.

2. Navigate to the docker folder of the extracted distribution.

3. Edit the credentials.txt file by updating the placeholder values for Access key ID and Secret access key with the values provided by Axiomatics.

   note

   These are the same values that were used in setting up AWS CLI.

4. Optionally, you can run ASM on a machine with a hostname other than the default as follows:

   Change the default hostname

   1. Navigate to the docker folder of the extracted distribution.
   2. Update the HOST variable in the .env file. The default value is localhost.
   3. Save the file and exit.

5. Copy a valid ASM license file to the docker folder.

   note

   This file is provided separately by Axiomatics.

6. Enable the BuildKit feature of Docker:

   • Linux/macOS
   • Windows

   *:first-child]:mt-0>

   export DOCKER_BUILDKIT=1

   *:first-child]:mt-0 hidden>

   Run the following command using PowerShell:

   $Env:DOCKER_BUILDKIT=1

7. Configure the SSL Certificate common name.

   In production environments, you should import trusted certificates only, while in dev and test environments you have the ability to create a self-signed certificate.

   • Import
   • Create

   *:first-child]:mt-0>

   ASM requires a PKCS#12 (Public Key Cryptography Standard #12) certificate. In case you already have a certificate with different format such as .pem, you should convert it to PKCS#12. The certificate file must be named cert.keystore.p12. During the creation of the certificate, the name (or alias) must be set to server.

   1. Navigate to the docker/api.gateway/certs/ folder of the extracted distribution.
   2. Copy your certificate to this folder.

   *:first-child]:mt-0 hidden>

   Generate a self-signed certificate as follows:

   1. Navigate to the docker folder of the extracted distribution.

   2. Open the .env file and update the following entries:

      • CERTIFICATE_CN with your common name
      • CERTIFICATE_KEY_STORE_PASSWORD with your password

   3. Generate the certificate:

   • Linux/macOS
   • Windows

   *:first-child]:mt-0>

   1. From the docker/api.gateway/certs/ folder, run the following command.

   sh generate_self_signed_certificate.sh

   2. Make sure that the following files were created:
      • cert.keystore.p12
      • server.crt

   *:first-child]:mt-0 hidden>

   1. From the docker\api.gateway\certs folder, run the following commands using PowerShell.

   warning

   In the first command, replace <your_cert_key_store_pw> and <your_cert_cn> with the same values that were previously used in the .env file.

   docker build -t certificate -f ./Dockerfile.cert . --build-arg CERTIFICATE_KEY_STORE_PASSWORD=<your_cert_key_store_pw> --build-arg CERTIFICATE_CN=<your_cert_cn>

   docker create --name cert certificate; docker cp cert:/cert.keystore.p12 ./cert.keystore.p12; docker cp cert:/server.crt ./server.crt; docker rm -f cert; docker image rm certificate

   2. Make sure that the following files were created:
      • cert.keystore.p12
      • server.crt

8. Start the installation process.

   • With Dashboard
   • Without Dashboard

   *:first-child]:mt-0>

   From the docker directory, start up your application.

   docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml up --build

   warning

   The docker-compose installation process uses the overriding functionality of Docker Compose for multiple compose files. The Compose files arguments order should be kept as is in the installation command.

   *:first-child]:mt-0 hidden>

   From the docker directory, start up your application.

   docker-compose up --build

   This starts ASM without InfluxDB and with the Dashboard functionality disabled.

Log in to ASM

1. After the installation has finished, open a web browser window and go to:

   • Default hostname
   • Custom hostname

   *:first-child]:mt-0>

   https://localhost/asm if you are using the default hostname.

   *:first-child]:mt-0 hidden>

   Append /asm to the hostname you are using. For example, https://example.com/asm.

2. The login page for ASM displays. Use the default credentials:

   • Username: asm-admin
   • Password: password

   You will immediately be prompted to change the password. After doing so, you are logged in to ASM for the first time.

Useful information and commands

Stop ASM

• With Dashboard
• Without Dashboard

*:first-child]:mt-0>

From the docker directory, stop your application.

docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml stop

*:first-child]:mt-0 hidden>

From the docker directory, stop your application.

docker-compose stop

Restart ASM

• With Dashboard
• Without Dashboard

*:first-child]:mt-0>

From the docker directory, restart your application.

docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml up

*:first-child]:mt-0 hidden>

From the docker directory, restart your application.

docker-compose up

Data persistence using volumes

ASM implements volumes for externalizing the data state, that is, ensuring the persistence of data generated by and used by Docker containers.

No further configuration is necessary. If more information is required, read the Use volumes topic of the Docker documentation.

note

Volumes do not create a folder on the host machine, but are managed by Docker commands. See the Backup, restore, or migrate data volumes topic of the Docker documentation for more information about all the possible user actions like deletion, backups, restore, migration, etc.

What's next?

Add users

During the deployment, a Keycloak service was also installed, to serve as an authentication module for the users of ASM. Only a default administrative user is created automatically at this time. All other users must be created and assigned a role in Keycloak, before they can log in to ASM.

To add more users and map them to roles you must use Keycloak as described in Manage users in Keycloak. Then, you can assign them to projects following the instructions in the Users and projects topic.

warning

For deployments with Policy Designer, you should also configure Keycloak accordingly.

Additional configuration

Once the installation of ASM has been verified as successful, there are additional configurations you may want to consider.