Installation of agentMET4FOF

As already mentioned in the README, agentMET4FOF can either be installed as a Python package or launched in a Docker container.

Note that agentMET4FOF is made for Python 3.8 or higher and should work best with Python 3.11.

Install agentMET4FOF as a Python package

The installation of agentMET4FOF is as straightforward as the Python ecosystem suggests. In the video tutorial series linked in the README we guide you through every step until you have agentMET4FOF running on your machine.

If you want to take the steps manually we guide you through in this document.

Set up a virtual environment

For the motivation of creating a virtual environment for your installation of the agents check the official Python docs on that topic . You have the option to do this with Anaconda, if you already have it installed, or use the Python built-in tool venv. The commands differ slightly between Windows and Mac/Linux or if you use Anaconda .

Create a `venv` Python environment on Windows

In your Windows PowerShell execute the following to set up a virtual environment in a folder of your choice.

PS C:> cd C:\LOCAL\PATH\TO\ENVS
PS C:\LOCAL\PATH\TO\ENVS> py -3 -m venv agentMET4FOF_venv
PS C:\LOCAL\PATH\TO\ENVS> agentMET4FOF_venv\Scripts\activate

Proceed to the next step.

Create a `venv` Python environment on Mac & Linux

In your terminal execute the following to set up a virtual environment in a folder of your choice.

$ cd /LOCAL/PATH/TO/ENVS
$ python3 -m venv agentMET4FOF_venv
$ source agentMET4FOF_venv/bin/activate

Proceed to the next step.

Create an Anaconda Python environment

To get started with your present Anaconda installation just go to Anaconda prompt and execute

$ cd /LOCAL/PATH/TO/ENVS
$ conda env create --file /LOCAL/PATH/TO/agentMET4FOF/environment.yml 

That’s it!

Install agentMET4FOF via `pip`

Once you activated your virtual environment, you can install agentMET4FOF via:

pip install agentMET4FOF

Collecting agentMET4FOF
[...]
Successfully installed agentMET4FOF-[...] [...]

That’s it!

Use agentMET4FOF from inside a Docker container

Every version of agentMET4FOF since v0.9.1dev is additionally accompanied by a so-called Docker image. With its help, agentMET4FOF can be launched quickly on any computer with a Docker installation without installing Python. agentMET4FOF can then be used directly in the browser using the supplied or your own Jupyter notebooks and even the dashboard can be visited in the browser after its launch. The following steps are required for this.

Install Docker
a) Start a container from the image for local use

b) Deploy the containerized agents via a webserver

Install Docker

The official Docker documentation guides you through. Please continue with the next step, once you completed the Docker installation.

Start a container from the image for local use

You can download and launch the Docker image straight away with Docker’s built-in run command

> docker run -p 8888:8888 -p 8050:8050 --rm met4fof/agentMET4FOF

In this command’s output you will find the usual Jupyter Notebook token URL, which you can open in your browser. After starting an agent network in one of the tutorials or your own notebooks, you will find the dashboard URL in the notebook’s output resembling something like http://0.0.0.0:8050.

Deploy the containerized agents via a webserver

To make the agents accessible via a TCP/IP network such as the internet using a web server like Nginx, all that is required is the correct webserver configuration. The example configuration presented here will spawn the container so that the Jupyter Notebook server is accessible via http://agent.domain.com, and the dashboard is accessible after start-up under http://agent.domain.com/YOUR_FOLDER_NAME_OF_CHOICE.

Start the container with the dashboard at a subfolder

Download and launch the container with

> docker run -p 8888:8888 -p 8050:8050 --rm  \ 
--env DASH_URL_BASE_PATHNAME=/YOUR_FOLDER_NAME_OF_CHOICE/ met4fof/agentMET4FOF

This ensures, that the dashboard will be reachable under whatever domain you are using followed by /YOUR_FOLDER_NAME_OF_CHOICE.

Configure the Nginx

We assume you are confident in using Nginx in general. The corresponding configuration should contain the following server blocks to ensure the Jupyter Notebook server is working, as well as the dashboard

server {
        server_name agent.domain.com;

        location / {
            proxy_pass http://127.0.0.1:8888;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

            # websocket headers
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header X-Scheme $scheme;

            proxy_buffering off;
        }

        location /YOUR_FOLDER_NAME_OF_CHOICE/ {
            proxy_pass http://127.0.0.1:8050/YOUR_FOLDER_NAME_OF_CHOICE/;
        }

    [...]

}