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.5 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 documentationOpens in a new tab.

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 AWS documentationOpens in a new tab. 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.5.0-0/axiomatics-services-manager-7.5.0-0.zip axiomatics-services-manager-7.5.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

   export DOCKER_BUILDKIT=1

   Windows

   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

   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.

   Create

   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

      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

      Windows

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

         Important

         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. Initiate the build process of the ASM service. You can choose to include the Dashboard functionality or not, depending on your needs.

   Dashboard enabled

   From the docker directory, start up your application.

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

   Important

   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.

   Dashboard disabled

   From the docker directory, start up your application.

   docker-compose up --build

   This command starts ASM without InfluxDB and disables the Dashboard functionality.

Log in to ASM

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

   Default hostname

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

   Custom hostname

   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

Dashboard enabled

From the docker directory, stop your application.

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

Dashboard disabled

From the docker directory, stop your application.

docker-compose stop

Restart ASM

Dashboard enabled

From the docker directory, restart your application.

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

Dashboard disabled

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 volumesOpens in a new tab 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 volumesOpens in a new tab 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.

Important

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.