Skip to main content
Version: 7.2

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.2.0 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.2.0-0/axiomatics-services-manager-7.2.0-0.zip axiomatics-services-manager-7.2.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

    If you want to run ASM on a machine with a hostname other than localhost, you have to update the hostname and the SSL Certificate common name before building and running ASM.

    Configure the 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.

    Configure the SSL Certificate common name

    There are two ways to configure the SSL Certificate. The first one generates a self-signed SSL Certificate, and should be used in dev and test environments. The second provides the ability to import trusted certificates, and should be used in production environments.

    Option 1: Generate a self-signed certificate

    1. Navigate to the docker folder of the extracted distribution.
    2. In the .env file, update the value of the SELF_SIGNED variable to true.
    3. In the .env file, update the value of the CERTIFICATE_CN variable. The default is *.
      This is the Common Name of the certificate (CN) to be generated.
    4. Save the file and exit.

    Option 2: Import a certificate

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

    1. Navigate to the docker folder of the extracted distribution.
    2. In the .env file, update the value of the SELF_SIGNED variable to false.
    3. Copy the cert.keystore.p12 certificate file into the docker/api.gateway/resources/ folder.
    4. 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:

    $Env:DOCKER_BUILDKIT=1

  7. If you will be using Policy Designer, open the docker/docker-compose.yml file and set the following:

    Add the alias of the IdP to be used by Policy Designer

    This is required only if you will be using Policy Designer.

    ParameterValue
    PD_IDP_NAMEThe alias of the IdP that will be configured later in Keycloak to work with Policy Designer. Learn more about the Policy Designer Keycloak configuration.
    The default is "google". Other available options:
    User-defined
    - OpenID Connect v1.0: Make sure that you use the same alias both here and in Keycloak!
    - Keycloak OpenID Connect: Make sure that you use the same alias both here and in Keycloak!
    Social
    - GitHub: "github"
    - Facebook: "facebook"
    - LinkedIn: "linkedin"
    - Instagram: "instagram"
    - Microsoft: "microsoft"
    - BitBucket: "bitbucket"
    - Twitter: "twitter"
    - Openshift v4: Make sure that you use the same alias both here and in Keycloak!
    - Openshift v3: Make sure that you use the same alias both here and in Keycloak!
    - GitLab: "gitlab"
    - StackOverfIow: "stackoverflow"
    Note: SAML is not supported.
    Important: The value should be in lowercase and enclosed in double quotation marks.
    Important: The IdP cannot be changed after the installation process is complete.
    Apply your branding to Policy Designer (optional)

    Optionally, if you want to apply your own branding to the Policy Designer interface, you should also set the following:

    ParameterValue
    PD_LOGOThe path to the logo image file displayed in the upper left corner of the Policy Designer interface.
    The default is "./assets/logo.svg" and the file contains the Axiomatics logo.
    Important: If changed, the value should be a valid URL pointing to a JPG/JPEG, PNG, or SVG file. It is recommended that the resolution of the image file is 210x50 pixels.
    PD_APP_NAMEThe app name/title displayed next to the logo and on the browser window.
    The default is "Policy designer".
    Important: The limit is 100 characters.
    PD_MAIN_COLORThe main color used in the Policy Designer interface, for buttons and highlighted components.
    The default is "#0274C1".
    Important: Replacement colors should be in hexadecimal notation.
    PD_BACKGROUND_COLORThe background color used in the Policy Designer interface.
    The default is "#F2F5F8".
    Important: Replacement colors should be in hexadecimal notation.

  8. Start the installation process.

    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.

Log in to ASM​

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

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

  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​

From the docker directory, stop your application. 

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

Restart ASM​

From the docker directory, restart your application. 

docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml 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.

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.