SCREEN

In this guide, you will install an Akamas-in-a-box, which is a full-functional Akamas instance as a Virtual Machine (VM), running on your workstation or in the cloud.

What you will learn

What you will need

The minimum requirements to get Akamas running are:

These requirements refer to the VM that hosts Akamas. If you are creating it on your desktop or laptop it should have at least 4 Cores and 12GB of RAM to effectively run the Akamas VM.

To get started, you only need the following:

This section describes how to build a fresh Ubuntu 20.04 VM on your workstation with few commands using Multipass.

Multipass Overview

The following picture represents the high-level architecture of how Akamas operates in this scenario. As this picture illustrates, the Akamas commands in this guide need to be executed from an Akamas shell in the VM while those related to Multipass need to be executed from a shell on your workstation (the host running the VM).

Scenario

Install Multipass

First of all, get Multipass installed following the instructions on the multipass website. Multipass is a lightweight VM manager that provides the fastest way to create an Ubuntu VM on Linux, Windows, or macOS.

Create your VM with Multipass

Once Multipass is installed, you can create an Ubuntu 20.04 instance with the resources required by Akamas by executing the following command:

multipass launch -c 2 -m 8G -d20G -n akamas

Once this step is complete, you can check the instance IP (note this down, it will be required later)

multipass list

Now you can launch a shell logged into this instance:

multipass shell akamas

At this point you should have your VM up and running.

To get Akamas installed, you just need to first download the installation script:

curl -o akamas-in-a-box.sh get.akamas.io

and then run it:

sudo bash akamas-in-a-box.sh install

Please take into account that this installation procedure may take a while as it has to first download the entire Akamas software and then boot all Akamas services. Depending on how fast is your internet connection, please plan from 30 to 60 minutes to get this step done.

Once the installation process is completed, you can verify if the installation has been successful. Please take into account that right after the installation, Akamas services are automatically started for the first time and that this may require a few more minutes.

You can verify if Akamas services are up and running by executing the following command or by accessing directly the UI (see next section):

akamas status

Once Akamas services are up and running, you can access the Akamas UI.

You can retrieve the IP address of your Akamas instance from the dashboard of your cloud service provider or, if you are running on Multipass on your workstation, by executing the following command from the host machine:

multipass list

Now you can open your browser and type this IP address to get access the Akamas login page:

SCREEN

At this point, you are almost done: you just need to install the Akamas license.

To install the Akamas license, you need to upload the license file which contains your license key on your Akamas instance. For example, you can leverage Multipass to transfer the license file by running the following command from the host system:

multipass transfer license.ak akamas:license.ak

Alternatively, you can put the license key into a file using your favorite text editor. Also in this case we assume the license file to be named license.ak.

Once you have the license file on your VM, you can install the license you have been provided by running the following commands from inside the Akamas shell (the path to the license file may be also specified) and finally log into Akamas using your credentials (that you received from Akamas support).

akamas install license license.ak

Congratulations, your Akamas instance is now fully installed and ready to be used!

Now that you have Akamas installed and ready to be used for creating optimization studies, it is now time for having fun with AI-driven performance optimization!

Here are a couple of recommended next steps for you:

© Akamas Spa 2018-present. Akamas and the Akamas logo are registered trademarks of Akamas Spa.

Multipass won't resume

Issue: when resuming the Multipass instance on a Linux machine, you get the error snap-update-ns failed with code 1

Solution: run the following commands to restart snap:

sudo apparmor_parser -r /var/lib/snapd/apparmor/profiles/snap*
sudo snap disable multipass
sudo snap enable multipass

Invalid locale

Issue: The Akamas CLI fails because the configured locale is invalid with an error similar to the following:

[15599] Failed to execute script akamas
Traceback (most recent call last):
  File "akamas.py", line 73, in <module>
  File "click/core.py", line 829, in __call__
  File "click/core.py", line 760, in main
  File "click/_unicodefun.py", line 130, in _verify_python3_env
RuntimeError: Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment. Consult https://click.palletsprojects.com/python3/ for mitigation steps.

This system supports the C.UTF-8 locale which is recommended. You might be able to resolve your issue by exporting the following environment variables:

    export LC_ALL=C.UTF-8
    export LANG=C.UTF-8

Click discovered that you exported a UTF-8 locale but the locale system could not pick up from it because it does not exist. The exported locale is 'en_US.UTF-8' but it is not supported

Solution: update the locale running export LC_ALL={locale} LANG={locale} setting one of the values returned by locale -a. Then, run sudo ./akamas-in-a-box.sh install-cli to complete the configuration of the Akamas CLI.

The installation script fails to install on CentOS / RHEL 7.x

Issue: The script fails with an error similar to the following:

Loaded plugins: amazon-id, langpacks, search-disabled-repos
https://download.docker.com/linux/rhel/7/x86_64/stable/repodata/repomd.xml: [Errno 14] HTTPS Error 404 - Not Found
Trying other mirror.
To address this issue please refer to the below knowledge base article

https://access.redhat.com/articles/1320623

If above article doesn't help to resolve this issue please open a ticket with Red Hat Support.



 One of the configured repositories failed (Docker CE Stable - x86_64),
 and yum doesn't have enough cached data to continue. At this point the only
 safe thing yum can do is fail. There are a few ways to work "fix" this:

     1. Contact the upstream for the repository and get them to fix the problem.

     2. Reconfigure the baseurl/etc. for the repository, to point to a working
        upstream. This is most often useful if you are using a newer
        distribution release than is supported by the repository (and the
        packages for the previous distribution release still work).

     3. Run the command with the repository temporarily disabled
            yum --disablerepo=docker-ce-stable ...

     4. Disable the repository permanently, so yum won't use it by default. Yum
        will then just ignore the repository until you permanently enable it
        again or use --enablerepo for temporary usage:

            yum-config-manager --disable docker-ce-stable
        or
            subscription-manager repos --disable=docker-ce-stable

     5. Configure the failing repository to be skipped, if it is unavailable.
        Note that yum will try to contact the repo. when it runs most commands,
        so will have to try and fail each time (and thus. yum will be be much
        slower). If it is a very temporary problem though, this is often a nice
        compromise:

            yum-config-manager --save --setopt=docker-ce-stable.skip_if_unavailable=true

failure: repodata/repomd.xml from docker-ce-stable: [Errno 256] No more mirrors to try.
https://download.docker.com/linux/rhel/7/x86_64/stable/repodata/repomd.xml: [Errno 14] HTTPS Error 404 - Not Found

Solution: manually install Docker following the official guide and re-run the Akamas installation scripts.

Docker is not running

Issue: The startup of the services fails with the following error:

Starting Akamas..
[1682] Failed to execute script docker-compose
Traceback (most recent call last):
  File "urllib3/connectionpool.py", line 677, in urlopen
  File "urllib3/connectionpool.py", line 392, in _make_request
  File "http/client.py", line 1277, in request
  File "http/client.py", line 1323, in _send_request
  File "http/client.py", line 1272, in endheaders
  File "http/client.py", line 1032, in _send_output
  File "http/client.py", line 972, in send
  File "docker/transport/unixconn.py", line 43, in connect
FileNotFoundError: [Errno 2] No such file or directory

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "requests/adapters.py", line 449, in send
  File "urllib3/connectionpool.py", line 727, in urlopen
  File "urllib3/util/retry.py", line 410, in increment
  File "urllib3/packages/six.py", line 734, in reraise
  File "urllib3/connectionpool.py", line 677, in urlopen
  File "urllib3/connectionpool.py", line 392, in _make_request
  File "http/client.py", line 1277, in request
  File "http/client.py", line 1323, in _send_request
  File "http/client.py", line 1272, in endheaders
  File "http/client.py", line 1032, in _send_output
  File "http/client.py", line 972, in send
  File "docker/transport/unixconn.py", line 43, in connect
urllib3.exceptions.ProtocolError: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "docker/api/client.py", line 214, in _retrieve_server_version
  File "docker/api/daemon.py", line 181, in version
  File "docker/utils/decorators.py", line 46, in inner
  File "docker/api/client.py", line 237, in _get
  File "requests/sessions.py", line 543, in get
  File "requests/sessions.py", line 530, in request
  File "requests/sessions.py", line 643, in send
  File "requests/adapters.py", line 498, in send
requests.exceptions.ConnectionError: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "docker-compose", line 3, in <module>
  File "compose/cli/main.py", line 80, in main
  File "compose/cli/main.py", line 189, in perform_command
  File "compose/cli/command.py", line 70, in project_from_options
  File "compose/cli/command.py", line 153, in get_project
  File "compose/cli/docker_client.py", line 43, in get_client
  File "compose/cli/docker_client.py", line 170, in docker_client
  File "docker/api/client.py", line 197, in __init__
  File "docker/api/client.py", line 222, in _retrieve_server_version
docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

Solution: Check that the Docker service is installed but inactive running sudo systemctl is-active docker, then start it with sudo systemctl start docker and re-run the Akamas installation script.