Preliminary steps

Please make sure to read the Getting Started section before installing Akamas.

Before installing Akamas, please follow these steps:

1. Review hardware, software, and network prerequisites

2. Install all Akamas dependencies

Installation steps

Please follow these steps to install the Akamas Server:

1. Install the Akamas Server

2. Install the Akamas CLI

3. Verify the Akamas Server

4. Install an Akamas license

Please also read the section on how to troubleshoot the installation and how to manage the Akamas Server. Finally, read the relevant sections of Integrating Akamas to integrate Akamas into your specific ecosystem.

Before installing the Akamas Server please make sure to review all the following requirements:

• Hardware requirements

• Software requirements

• Network requirements

Running in your data center

The following table provides the minimal hardware requirements for the virtual or physical machine used to install the Akamas server in your data center.

Running on AWS EC2

To run Akamas on an AWS Instance you need to create a new virtual machine based on one of the supported operating systems. You can refer to AWS documentation for step-by-step instructions on creating the instance.

As shown in the following diagram, you can create the Akamas instance in the same AWS region, Virtual Private Cloud (VPC), and private subnet as your own already existing EC2 machines and by creating/configuring a new security group that allows communication between your application instances and Akamas instance. The inbound/outbound rules of this security group must be configured as explained in the Networking Requirements section of this page.

It is recommended to use an m6a.xlarge instance with at least 70GB of disks of type GP2 or GP3 and select the latest LTS version of Ubuntu.

Supported AWS Regions

Akamas can be run in any EC2 region.

You can find the latest version supported for your preferred region here.

AWS Service Limits

Before installing Akamas on an AWS Instance please make sure to meet your AWS service limits (please refer to the official AWS documentation here).

Operating System

The following table provides a list of the supported operating systems and their versions.

On RHEL systems Akamas containers might need to be run in privileged mode depending on how Docker was installed on the system.

Software packages

The following table provides a list of the required Software Packages (also referred to as Akamas dependencies) together with their versions.

The exact version of these prerequisites is listed in the following table:

Read more about how to set up Akamas dependencies.

Akamas user

To install and run Akamas it is recommended to create a dedicated user (usually "akamas"). The Akamas user is not required to be in the sudoers list but can be added to the docker (dockeroot) group so it can run docker and docker-compose commands.

Make sure that the Akamas user has the read, write, and execute permissions on /tmp. If your environment does not allow writing to the whole /tmp folder, please create a folder /tmp/build and assign read and write permission to the Akamas user on that folder.

Internet access

Internet access is required for Akamas online installation and updated procedures and allows retrieving the most updated Akamas container images from the Akamas private Amazon Elastic Container Registry (ECR).

If internet access is not available for policies or security reasons, Akamas installation and updates can be executed offline.

Internet access from the Akamas server is not mandatory but it’s strongly recommended.

Ports

The following table provides a list of the ports on the Akamas server that have to be reachable by Akamas administrators and users to properly operate the system.

In the specific case of AWS instance and customer instances sharing the same VPC/Subnet inside AWS, you should:

• open all of the ports listed in the table above for all inbound URLs (0.0.0.0/32) on your AWS security group

• open outbound rules to all traffic and then attach this AWS security group (which must reside inside a private subnet) to the Akamas machine and all customer application AWS machines

This page will guide you through the installation of software components that are required to get the Akamas Server installed on a machine. Please read the Akamas dependencies for a detailed list of these software components for each specific OS.

While some links to official documentation and installation resources are provided here, please make sure to refer to your internal system engineering department to ensure that your company deployment processes and best practices are correctly matched.

Dependencies Setup

As a preliminary step before installing any dependency, it is strongly suggested to create a user named akamas on your machine hosting Akamas Server.

Docker

Follow the reference documentation to install docker on your system.

Docker installation guide: https://docs.docker.com/engine/install

Docker compose is already installed since Docker 23+. To install it on previous versions of Docker follow this installation guide: https://docs.docker.com/compose/install/

AWS CLI v2: https://docs.aws.amazon.com/cli/latest/userguide

Verify dependencies

As a quick check to verify that all dependencies have been correctly installed, you can run the following commands

• Docker:

  Copy

  docker run hello-world

• Docker compose :

  Copy

  docker compose --version

• AWS CLI:

  Copy

  aws --version

Akamas is deployed as a set of containerized services running on Docker and managed via Docker Compose. The latest version of the Akamas Docker Compose file and all the images required by Docker can be downloaded from the AWS ECR repository.

Two installation modes are available:

• online installation mode, in case the Akamas Server has access to the Internet - installation behind a proxy server is also supported.

• offline installation mode, in case the Akamas Server does not have access to the Internet.

Akamas is deployed as a set of containerized services running on Docker and managed via Docker Compose. In the online installation mode, the latest version of the Akamas Docker Compose file and all the images required by Docker can be downloaded from the AWS ECR repository.

In case the Akamas Server is behind a proxy server please also read how to setup Akamas behind a Proxy.

Get Akamas Docker artifacts

It is suggested first to create a directory akamas in the home directory of your user, and then run the following command to get the latest compose file:

cd ~
mkdir akamas
cd akamas
curl -O https://s3.us-east-2.amazonaws.com/akamas/compose/3.6.2/docker-compose.yml

Configure Akamas environment variables

To log into AWS ECR and pull the most recent Akamas container images, you need to set the AWS authentication variables to the appropriate values provided by Akamas Customer Support Services by running the following command. To configure Akamas, you should set the following environment variables:

To configure Akamas, you should set the following environment variables:

• AKAMAS_CUSTOMER: the customer name matching the one referenced in the Akamas license.

• AWS_ACCESS_KEY_ID: the access key for pulling the Akamas images

• AWS_SECRET_ACCESS_KEY: the secret access key for pulling the Akamas images

• AWS_DEFAULT_REGION: Unless specified by the support team keep the value to us-east-2

• AKAMAS_BASE_URL: the endpoint in the Akamas APIs that will be used to interact with the CLI, typically https://<akamas server DNS address>

To avoid losing your environment variables for future upgrades, it is suggested to keep them in the .env file. Launch the following command from the same folder where the docker-compose.yml is stored, replacing the parameters in the brackets <>:

# Required variables
AKAMAS_CUSTOMER=<your name or your organization name>
AWS_ACCESS_KEY_ID=<your access key id>
AWS_SECRET_ACCESS_KEY=<your secret access key>
AKAMAS_BASE_URL=https://<akamas server DNS address>
AWS_DEFAULT_REGION=us-east-2

# Optional variables
# Database passwords
DEFAULT_DATABASE_PASSWORD=
KEYCLOAK_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_keycloak}
ANALYZER_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_analyzer}
CAMPAIGN_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_campaign}
LICENSE_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_license}
OPTIMIZER_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_optimizer}
ORCHESTRATOR_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_orchestrator}
SYSTEM_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_system}
TELEMETRY_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_telemetry}
# Docker volumes prefix
COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME:-akamas}

Start Akamas

To log into AWS ECR and pull the most recent Akamas container images you also need to set the AWS authentication variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION) with the values provided by Akamas Customer Support Services. You can leverage the .env file previously created with the following command:

source ./.env
aws ecr get-login-password --region us-east-2 | docker login -u AWS --password-stdin https://485790562880.dkr.ecr.us-east-2.amazonaws.com

You can start installing the Akamas server by running the following AWS CLI commands:

docker compose up -d

This section describes how to setup an Akamas Server behind a proxy server and to allow Docker to connect to the Akamas repository on AWS ECR.

Configure Docker daemon

First, create the /etc/systemd/system/docker.service.d directory if it does not already exists. Then create or update the /etc/systemd/system/docker.service.d/http-proxy.conf file with the variables listed below, taking care of replacing <PROXY> with the address and port (and credentials if needed) of your target proxy server:

[Service]
Environment="HTTP_PROXY=<PROXY>"
Environment="HTTPS_PROXY=<PROXY>"

Once configured, flush the changes and restart Docker with the following commands:

sudo systemctl daemon-reload
sudo systemctl restart docker

For more details, refer to the official documentation page: Control Docker with systemd.

Configure the Akamas containers

To allow the Akamas services to connect to addresses outside your intranet, the Docker instance needs to be configured to forward the proxy configuration to the Akamas containers.

Update the ~/.docker/config.json file adding the following field to the JSON, taking care to replace <PROXY> with the address (and credentials if needed) of your target proxy server:

{
  # ...
  "proxies": {
    "default": {
      "httpProxy": "<PROXY>",
      "httpsProxy": "<PROXY>",
      "ftpProxy": "<PROXY>",
      "noProxy": "localhost,127.0.0.1,/var/run/docker.sock,database,optimizer,campaign,analyzer,telemetry,log,elasticsearch,metrics,system,license,store,orchestrator,airflow-db,airflow-webserver,kong-database,kong,user-service,keycloak,logstash,kibana,akamas-ui,grafana,prometheus,node-exporter,cadvisor,konga,benchmark"
    }
  }
}

For more details, refer to the official documentation page: Configure Docker to use a proxy server.

Run Akamas

Set the following variables to configure your working environment, taking care to replace <PROXY> with the address (and credentials if needed) of your target proxy server:

export HTTP_PROXY='<PROXY>'
export HTTPS_PROXY='<PROXY>'

Once configured, you can log into the ECR repository through the AWS CLI and start the Akamas services manually.

Akamas is deployed as a set of containerized services running on Docker and managed via Docker Compose. In the offline installation mode, the latest version of the Akamas Docker Compose file and all the images required by Docker cannot be downloaded from the AWS ECR repository.

Get Akamas Docker artifacts

Get in contact with Akamas Customer Services to get the latest versions of the Akamas artifacts uploaded to a location of your choice on the dedicated Akamas Server.

Akamas installation artifacts will include:

• images.tar.gz: a tarball containing Akamas main images.

• docker-compose.yml: docker-compose file for Akamas.

• akamas: the binary file of the Akamas CLI that will be used to verify the installation.

Import Docker images

A preliminary step in the offline installation mode is to import the shipped Docker images by running the following commands in the same directory where the tar files have been stored:

cd <your bundle files location>
docker image load -i images.tar.gz

Mind that this import procedure could take some time!

Configure Akamas environment variables

To configure Akamas, you should set the following environment variables:

• AKAMAS_CUSTOMER: the customer name matching the one referenced in the Akamas license.

• AKAMAS_BASE_URL: the endpoint in the Akamas APIs that will be used to interact with the CLI, typically https://<akamas server DNS address>

To avoid losing your environment variables for future upgrades, it is suggested to keep them in the .env file, stored in the same directory as the docker-compose.yml:

# Required variables
AKAMAS_CUSTOMER=<your name or your organization name>
AKAMAS_BASE_URL=https://<akamas server DNS address>

# Optional variables
## Database password. Use DEFAULT_DATABASE_PASSWORD to set a custom password for all databases
DEFAULT_DATABASE_PASSWORD=
## A custom password per each service can be set using the variables below, otherwise, the default is used. For example, for Kong's database, the password is `akamas_kong`.
KONG_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_kong}
AIRFLOW_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_airflow}
KEYCLOAK_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_keycloak}
ANALYZER_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_analyzer}
CAMPAIGN_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_campaign}
LICENSE_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_license}
OPTIMIZER_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_optimizer}
ORCHESTRATOR_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_orchestrator}
SYSTEM_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_system}
TELEMETRY_DATABASE_PASSWORD=${DEFAULT_DATABASE_PASSWORD:-akamas_telemetry}
# Docker volumes prefix
COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME:-akamas}

Run installation

To start Akamas you can now simply navigate into the akamas folder and run a docker-compose command:

cd <your docker-compose file location>
docker compose up -d

You may get the following error:

Error saving credentials: error storing credentials - err: exit status 1, out: Cannot autolaunch D-Bus without X11 $DISPLAY

This is a documented docker bug (see this link) that can be solved by installing the "pass" package:

• Ubuntu

sudo apt-get install -y pass

• RHEL

yum install pass

By default, Akamas uses the following ports for its UI:

• 80 (HTTP)

• 443 (HTTPS)

Depending on the configuration of your environment, you may want to change the default settings: to do so, you’ll have to update the Akamas docker-compose file.

Inside the docker-compose.yml file, scroll down until you come across the akamas-ui service. There you will find a specification as follows:

  akamas-ui:
    ports:
      - "443:443"
      - "80:80"

Update the YAML file by remapping the UI ports to the desired ports of the host.

  akamas-ui:
    ports:
      - "<YOUR_HTTPS_PORT_OF_CHOICE>:443"
      - "<YOUR_HTTP_PORT_OF_CHOICE>:80"

In case you were running Akamas with host networking, you are allowed to bind different ports in the container itself. To do so you can expand the docker-compose service by adding a couple of environment variables like this:

  akamas-ui:
    environment:
      - HTTP_PORT=<HTTP_CONTAINER_PORT>
      - HTTPS_PORT=<HTTPS_CONTAINER_PORT>
    ports:
      - "<YOUR_HTTPS_PORT_OF_CHOICE>:<HTTP_CONTAINER_PORT>"
      - "<YOUR_HTTP_PORT_OF_CHOICE>:<HTTPS_CONTAINER_PORT>"

Finally, apply the new configuration after updating the AKAMAS_BASE_URL environment variable to match the new protocol or port.

Akamas APIs and UI use plain HTTP when they are first installed. To enable the use of HTTPS you will need to:

1. Ask your security team to provide you with a valid certificate for your server. The certificate usually consists of two files with ".key" and ".pem" extensions. You will need to provide the Akamas server DNS name.

2. Create a folder named "certs" in the same directory as Akamas' docker-compose file;

3. Copy the ".key" and ".pem" files in the created "certs" folder and rename them to "akamas.key" and "akamas.pem" respectively. Ensure the files belong to the same user and group you use to run Akamas.

4. Restart two Akamas services by running the following commands:

   Copy

   cd <Akamas docker-compose file folder>
   docker compose restart akamas-ui kong

After the containers' reboot is complete you will be able to access the UI over HTTPS from your browser:

https://<akamas server name here>

If you previously set up AKAMAS_BASE_URL variable with http (e.g. http://my.domain) you should update it to use https (e.g. http://my.domain) then issue

docker compose up -d

Setup CLI to use HTTPS

Now that your Akamas server is configured to use HTTPS you can update the Akamas CLI configuration to use the secure protocol.

If you have not installed the Akamas CLI, follow the CLI installation guide. If you already have the CLI available, you can run the following command:

akamas init config

You will be prompted to enter some input, please value it as follows:

Api address [http://localhost:8000]: https://<akamas server dns address>:443/akapi
Workspace [default]: default
Verify SSL: [True]: True

You can test the connection by running:

akamas status

It should return 'OK', meaning Akamas has been properly configured to work over HTTPS.

Issues when installing Docker

Centos 7 and RHEL 7

Notice: this distro features a known issue since Docker default execution group is named dockerroot instead of docker . To make docker work edit (or create) /etc/docker/daemon.json to include the following fragment:

{
  "group": "dockerroot"
}

After editing or creating the file, please restart Docker and then check the group permission of the Docker socket (/var/run/docker.sock), which should show dockerroot as a group:

srw-rw----. 1 root dockerroot 0 Jul  4 09:57 /var/run/docker.sock

Then, add the newly created akamas user to the dockerroot group so that it can run docker containers:

sudo usermod -aG dockerroot <user_name>

and check the akamas user has been correctly added to dockerroot group by running:

lid -g dockerroot

Issues when running AWS CLI

In case of issues in logging in through AWS CLI, when executing the following command:

aws ecr get-login-password --region us-east-2

Please check that:

• Environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION are correctly set

• AWS CLI version is 2.0+

We recommend using the official AWS CLI installation guide for a smoother experience.

Issue when starting Akamas services

Akamas failed to start some services

Please notice that the very first time Akamas is started, up to 30 minutes might be required to initialize the environment.

In case the issue persists you can run the following command to identify which service is not able to start up correctly

akamas status -d

License service unable to access docker socket

In some systems, the Docker socket, usually located in /var/run/docker.sock can not be accessed within a container. This causes Akamas to signal this behavior by reporting the Access Denied error in the license service logs.

To overcome this limitation edit the docker-compose.yaml file adding the line privileged: true to the following services:

• License

• Optimizer

• Telemetry

• Airflow

The following is a sample configuration where this change is applied to the license service:

license:
  image: 485790562880.dkr.ecr.us-east-2.amazonaws.com/akamas/license_service:2.3.0
  container_name: license
  privileged: true

Finally, you can issue the following command to apply these changes

docker compose up -d

Missing Akamas Customer variable

When installing Akamas it’s mandatory to provide the AKAMAS_CUSTOMER variable as illustrated in the installation guide. This variable must match the one provided by Akamas representatives when issuing a license. If the variable is not properly exported license installation will fail with an error message indicating that the name of the customer installation does not match the one provided in the license.

You can easily inspect which value of this variable has been used when starting Akamas by running the following command on the Akamas server:

docker inspect license | grep AKAMAS_CUSTOMER

If you find out that the value is not the one you expect, you can update the .env file and then start again the license service by running:

docker compose up -d license

Once Akamas is up and running you can re-install your license.

Other issues

For any other issues please contact Akamas Customer Support Services.