Merge pull request #20 from idcc-dev/mike-move-doc-to-wiki

![AdvantEDGE-logo](./docs/images/AdvantEDGE-logo_Blue-01.png)

_Complete AdvantEDGE documentation is now available in the [AdvantEDGE Wiki](https://github.com/InterDigitalInc/AdvantEDGE/wiki)_

------

AdvantEDGE is a Mobile Edge Emulation Platform (MEEP) that runs on Docker & Kubernetes.

> AdvantEDGE provides an emulation environment, enabling experimentation with Edge Computing Technologies, Applications, and Services.  The platform facilitates users to explore edge / fog deployment models and their impact to applications and services in short and agile iterations.

Before getting started we recommend familiarity with key [AdvantEDGE concepts](docs/concepts.md)

## Getting started

To get started using AdvantEDGE, the following high-level steps are needed:

- Setup runtime environment (Ubuntu/Dockers/Kubernetes/Helm)

- Clone AdvantEDGE repo

- Install & Configure meepctl tool

- Deploy AdvantEDGE micro-services

Step-by-step details are available in the [Wiki](https://github.com/InterDigitalInc/AdvantEDGE/wiki#getting-started)

- [Setup runtime environment (Ubuntu/Dockers/Kubernetes/Helm)](docs/setup_runtime.md)

- Clone the AdvantEDGE repo

  ```

  git clone https://github.com/<your-fork>/AdvantEDGE.git

  ```

  > **Note:** Assumes local gitdir = `~/AdvantEDGE`

- Obtain AdvantEDGE binaries

  - [Build from source](#building)

  - Optionally use pre-built binaries (from GitHub release)

    ```

    # Get bin folder tarball from desired release

    cd ~/AdvantEDGE

    tar -zxvf advantedge.<version>.linux-amd64.tar.gz

    ```

- Setup [*meepctl*](docs/meepctl/meepctl.md) tool

  - Copy to an executable path

    ```

    sudo cp ~/AdvantEDGE/bin/meepctl/meepctl /usr/local/bin/

    ```

  - Configure

    ```

    meepctl config set --ip <your-node-ip> --gitdir /home/<user>/AdvantEDGE

    ```

- [Deploy AdvantEDGE](docs/deploy.md)

- [Use AdvantEDGE](docs/use.md)

## Building

The backend portion of AdvantEDGE is implemented as a collection of micro-services in Golang.

- [Setup development environment (Ubuntu/Go/Node.js/NPM/Linters)](docs/setup_dev.md)

The frontend portion of AdvantEDGE is implemented using Javascript, React and Redux technologies.

- Clone the AdvantEDGE repo<br>

  `git clone https://github.com/<your-fork>/AdvantEDGE.git`<br>

  (*assuming local gitdir =* `~/AdvantEDGE`)

To re-build either of these components, you first need to setup the development environment and then use the meepctl tool.

- [Build AdvantEDGE](docs/build.md)

Step-by-step details are available in the [Wiki](https://github.com/InterDigitalInc/AdvantEDGE/wiki#building)

## Testing

The AdvantEDGE platform comes with automated system tests using Cypress.

The AdvantEDGE platform test procedures are described [here](docs/testing.md)

Step-by-step details are available in the [Wiki](https://github.com/InterDigitalInc/AdvantEDGE/wiki/test-advantedge)

## Upstream communication

We use GitHub issues.

So just open an issue in the repo to provide user feedback, report software bugs or request enhancements.

So just open an issue in the repo to provide user feedback, report bugs or request enhancements.

## Licensing

# AdvantEDGE Documents

Document | Description

-|-

[setup_dev.md](setup_dev.md)            | Setup development environment

[setup_runtime.md](setup_runtime.md)    | Setup runtime environment

[build.md](build.md)                    | Build the platform

[deploy.md](deploy.md)                  | Deploy the platform

[use.md](use.md)                        | Get started using it

[concepts.md](concepts.md)              | Define concepts

[testing.md](testing.md)                | Testing

Documentation is maintained in the [AdvantEDGE Wiki](https://github.com/InterDigitalInc/AdvantEDGE/wiki)

# Build Procedure

## Prerequisites

- Set up [AdvantEDGE Development Environment](setup_dev.md)

## Build & Install meepctl

The [_meepctl CLI tool_](meepctl/meepctl.md) tool is built & installed using a bash script.

```

cd ~/AdvantEDGE/go-apps/meepctl

./install.sh

```

A first time install of meepctl must also be configured.

```

meepctl config set --ip <your-node-ip> --gitdir /home/<user>/AdvantEDGE

```

## Build AdvantEDGE micro-services

The [_meepctl CLI tool_](meepctl/meepctl.md) is used to build the AdvantEDGE binaries using the [_meepctl build_](meepctl/meepctl_build.md) command.

```

meepctl build all

# To build a single micro-service:

# meepctl build <micro-service name>

```

>**NOTE**<br>

Linters are run by default on every build. To disable linting use the `--nolint` flag.

This command generates the _core_ micro-service binaries, as well as the frontend web application.

To deploy the new binaries, follow the [Deploy AdvantEDGE](deploy.md) procedure.

# AdvantEDGE Concepts

## Goal

- [Micro-service architecture](#micro-service-architecture)

- [Macro-network model](#macro-network-model)

- [Network characteristics](#network-characteristics)

- [Network mobility](#network-mobility)

- [External UE support](#external-ue-support)

- [Frontend](./concepts/frontend.md)

## Micro-service architecture

AdvantEDGE is a controller software that facillitates deployment of edge applications in a simulated network environment.

It is composed of a collection of micro-services that interact together to allow deployment and testing of edge scenarios.

AdvantEDGE micro-services are packaged in Docker containers which are designed to operate in a Kubernetes environment.

> _AdvantEDGE currently only supports single node K8s host deployment_

Containers belong to one of 3 groups

Groups | Description

---------|------------

_Core_   | micro-services implementing the AdvantEDGE controller functionality

_Dependency_ | 3rd party micro-services upon which the Core micro-services depends

_Scenario_ | containers implementing an edge application use case

High-level overview of AdvantEDGE micro-service architecture

![micro-service arch.](./images/architecture.png)

AdvantEDGE components have the following roles:

Component |Type| Role

---------|------------|------------

_Controller Engine_ |core| Orchestrate interactions between the user (GUI) and other micro-services

_Virtualization Engine_ |core| Deploy/Delete scenario containers

_Scenario Initializer_ |core| Dynamically modify scenario containers at deployment time

_Monitoring Engine_ |core| Monitor the state of core and scenario containers

_Traffic Controller Engine_ |core| Orchestrate application of network characteristics to the scenario containers

_Traffic Controller Sidecar_ |core| Apply location specific network characteristics to a scenario container. Sidecar is dynamically injected into scenario pods at deployment time

_Mobility Group Manager_ |core| Orchestrate edge application state relocation

_Couchdb_ |dep.| Store user scenarios

_Helm CLI + Tiller_ | dep.| Deploy K8s containers

_Redis_ | dep. | Store internal runtime data

_Elastic Stack_ | dep. | Monitoring pipeline

## Macro-network model

AdvantEDGE uses the following model to define a scenario.

![macro-network model](./images/model.png)

Layer | Description

---------|------------

_Scenario_ | Scenario is the top level component of the Macro-network model<br><br> <li>AdvantEDGE users creates scenarios <li>AdvantEDGE can store multiple scenarios <li>Each scenario is uniquely named <li> One scenario is deployed at a time (e.g. the "active" scenario)

_Logical Domain_ | Defines the number and types of domainsof within a scenario<br><br> <li>Internet/Distant cloud is the default domain <li> Each MNO represents a domain <li>Scenario layer defines Inter-Domain network characteristics for traffic crossing between domains

_Logical Zone_ | A domain can be decomposed in different zones<br><br> <li>Zones allow to group multiple Network locations together <li>Logical Domain layer defines Inter-Zone network characteristics for traffic crossing between zones

_Network Location_ | Defines locations within a zone where nodes attach to the network<br><br> <li>Also referred to as a Point of Attachment (PoA) <li>PoA may connect Fixed or Mobile terminals (e.g. edge/fog/cloud nodes, int./ext. UEs) <li>Logical Zone layer defines Inter-Fog, Inter-Edge & Edge-Fog network characteristics for traffic crossing between these network locations

_Physical Location_ | Defines the physical location of a device; each device in a system occupies its own unique physical location<br><br> <li>Defines the node type that occupies the physical location <li>Example of node types are edge,fog,cloud,internal UE, external UE <li>Mobile terminals may dynamically be changed of PoA at scenario runtime by sending a Mobility Event <li>Network Location layer defines the terminal link network characteristics

_Process_ | The "leaf" of the model tree; process represents an application executing at a specific Physical Location<br><br> <li>Each process is realized by deploying a container in K8s <li>Process are impacted by network characteristics as described [here](#network-characteristics) <li>External UEs have their process running outside of the AdvantEDGE platform as described [here](#external-ue-support)

## Network Characteristics

AdvantEDGE supports the following network characteristics: latency, jitter, throughput and packet loss

Characteristic | Description

---------|------------

_Latency_ | Amount of time that a packet takes to traverse a network to its final destination<br><br> <li>Expressed in milliseconds <li>In order to simplify scenario definition, AdvantEDGE uses a latency model; given a scenario with N nodes, a user therefore does not have to specify N x (N-1) latencies <li> Latency model has the following configuration points: Inter-Domain, Inter-Zones, Inter-Edge, Inter-Fog, Edge-Fog and Terminal Link <li>Latency experienced is the sum of latencies between the source and destination nodes <br><br>_NOTE: Latency is applied to **every** packet crossing the network regardless of direction; for example, each packet of the TCP Three-Way Handshake is equally affected when establishing a TCP connection (e.g. a total latency of 10ms betweeen 2 nodes =  30ms TCP session establishment time)_

_Jitter_ | Variation of the latency parameter<br><br> <li>Expressed as a percentage <li>Each latency in the model has its own jitter value

_Throughput_ | Maximum amount of data moved between two points in the network<br><br> <li>Expressed in Megabits per seconds (Mbps) <li>Throughput has the same configuration points as Latency <li>Throughput experienced between two nodes equals the minimum throughput observed on the data path  <br><br>_Limitation: Currently, throughput caps the maximum throughput between 2 nodes and does not take into account the data generated by other nodes. For example, an Inter-Zone throughput capped at 1 Mbps may effectively have 2 Mbps of traffic if two different nodes transmits data across zones; each node would be capped at 1Mbps._

_Packet Loss_ | Packet loss occurs when data packets travelling acrossthe network fail to reach their destination<br><br> <li>Expressed as a percentage <li>Packet Loss has the same configuration points as Latency <li>Packet Loss experienced between two nodes equals the maximum packet loss observed on the data path

## Network Mobility

AdvantEDGE implements an API that allows to trigger Network Mobility events.

With regards to the AdvantEDGE model, a network mobility event represents a Physical Location (e.g. a UE terminal) that changes its parent Network Locatioexternaln (e.g. a PoA). When such an event happens, the network characteristics affecting the moved UE are re-calculated by AdvantEDGE.

Mobility events are sent via the AdvantEDGE REST API and can be manually triggered from the AdvantEDGE frontend or alternatively trigerred by an experimenter's specific application.

## External UE support

AdvantEDGE supports experimenting with UEs external to the platform.

One of the complexities of supporting external UEs is applying network characteristics to these external nodes as if they were present on the simulation platform.

To enable this use case, AdvantEDGE needs to create a K8s pod that runs on the platform for **each** external UE. External UE then needs to access internal services (edge/fog/distant cloud) by going through their respective shadowing pod. This makes it possible for AdvantEDGE to track an external UE location through the network and to apply the required network characteristics to that UE.

# Frontend structure and main concepts

## Introduction

This document aims at providing a bird's eye view of the internals of the *_AdvantEDGE_* web frontend. The state of the application is briefly described and then the mechanism by which it is changed is outlined. This high-level overview should give the reader enough insight into the design choices to get started exploring and augmenting it.

The frontend has been implemented with the _React_ and _Redux_ javascript libraries and it is recommended that the reader be familiar with them.

Please take some time to read on [_React_](https://reactjs.org/docs/getting-started.html) and [_Redux_](https://redux.js.org/) libraries as needed.

## Overview

The frontend consists of 4 main tabs or pages:

Page | functionalities

----------- | ------------

Config      | <li>Scenario creation <li>Updating a scenario <li>Exporting <li> Importing a scenario

Execution   | <li> Scenario deployment <li>Mobility events <li>Network Characteristics updates

Monitor     | Monitoring dashboards

Settings    | General parameters e.g. automatic scenario refresh

For more details on concepts mentioned in the above table please refer to [AdvantEDGE concepts](https://github.com/idcc-dev/AdvantEDGE/blob/master/docs/concepts.md)

The state of the application has fields for the configuration, Execution and Settings page and also has a ```ui``` field which describes some high-level states of the UI, such as which page the user is curently on, among others.

The application state has the following structure:

 ``` Javascript

 {

    ui: {

        page: ...,

        eventCreationMode: true | false,

        currentEventType: UE_MOBILITY_EVENT | NETWORK_CHARACTERISICS_EVENT,

        devMode: true | false,

        automaticRefresh: true | false,

        refreshInterval: <in ms>,

        execShowApps: true | false

    },

    cfg: {

        type: {...},

        state: {...}

        scenario: {...} 

        vis: {...} 

        table: {...}

        elementConfiguration: {...}

        apiResults: {...}

     },

     exec: {

        type: {...}

        state: {...}

        scenario: {...}

        vis: {...}

        table: {...}

        selectedScenarioElement: {...}

        apiResults: {...}

     },

     settings: {

         ...

     },

 }

 ```

The following table describes the role of some of the paths in the `ui` part of the application state.

Path                     | Description

-------------------------|--------

`ui.page`                | The current selected page (`cfg`, `exec`, etc.) 

`ui.eventCreationMode`   | Says whether the creation pane is open

`ui.automaticRefresh`    | If `true` the scenario is refreshed periodically

`ui.refreshInterval`     | Interval at which the scenario is refreshed. Min is 500 ms

`ui.execShowApps`        | If apps are shown or not in the network visualization of the exec page.

The same for the `cfg` part of the state:

Path           | Description

---------------| --------------

`cfg.state`    | Whether a scenario is opened or not

`cfg.scenario` | The currently opened scenario in the config page

`cfg.vis`      | The data needed for the network visualization on the config page

`cfg.table`    | The data structure representing the working copy of the loaded scenario

`cfg.elementConfiguration.configuredElement` | The network element currently being worked on (creation, update etc.)

`cfg.apiResults`| Results of some api calls. _i.e._ available scenario to load etc.

The table for the `exec` part is similar but applies to the case of a deployed and running scenario:

Path           | Description

---------------|---------------

`exec.state`   | Says whether a scenarion is deployed or if the system is idle i.e. no scenario currently deployed.

`exec.state`   | The scenario that is currently deployed i.e. 'active'

`exec.table`   | The data structure representing the workable copy of the deployed scenario

`exec.selectedElement` | The currently selected network element in the deployed scenario along with it's network characteristics.

`exec.apiResults` | Results of some api calls.

The `settings` part of the state currently only has a boolean value named `settings.devMode`. In dev mode it is possible to play with some parameters of the visualization tool such as physics properties used in graph representation.

### Reducers

A _Redux_ application uses a special function called the _reducer_. It is often referred to as the _Root Reducer_ as in many apps it is composed from smaller reducer functions performing a similar task but on parts of the state only.

In general a _redux_ reducer function is a '_pure function_', that is, has no side-effects. It takes as its arguments an `action` and the current `state` of the application and computes a new state for the application. In turn, the main functionality of _React_ can be seen as a function that takes the `state` and through a `render` function outputs corresponding html markup. 

In the case of the _AdvantEDGE_ application, the root reducer is composed from more specialized reducers that individually compute state transistions for the following branches of the state tree: 

 `ui`, `cfg`, `exec` and `settings`.  In turn, `cfg` and `exec` are each created by combining lower-level reducers, one for each sub-branch of the state.

Please refer to the documentation on [Redux](https://redux.js.org/)  and [_React_](https://reactjs.org/docs/getting-started.html) for a more in depth explanation.

### Actions

The state of the application is updated through Redux _actions_ when user-initiated events occur or following responses from HTTP requests to the AdvantEDGE server.

The following diagram illustrates this general pattern as used in the _AdvantEDGE_ frontend.

 ![General Data Flow Pattern](../images/meep-frontend-data-flow-pattern.png "General Data Flow Pattern")

 Here are some of the actions that are used in the implementation of the _AdvantEDGE_ application.

 State Path          | Action Name          | Description

 --------------------|----------------------|--------------

`ui.page`            | `CHANGE_CURRENT_PAGE`| Will result in the specified page being shown to the user. It can be one of the 4 pages or tabs: `cfg`, `exec`, `monitor` or `settings`

`ui.currentDialog`   | `UI_CHANGE_CURRENT_DIALOG` | This is how, through an action, a modal dialog is shown to the user. Which dialog to show is specified in the payload of the action.

`cfg.elementConfiguration.configuredElement` | `CFG_ELEM_NEW` | Triggered when the user wants to add a new element to the scenario being worked on.

`cfg.elementConfiguration.configuredElement` | `CFG_ELEM_UPDATE` | Triggered when the user wants to update an element in the scenario being worked on.

`exec.table`         | `EXEC_CHANGE_TABLE`   | When triggered, the data representing the working copy of the deployed scenario is modified.

`exec.state.corePodsPhases` | `EXEC_CHANGE_CORE_PODS_PHASES` | Triggered periodically as the state of core pods is polled from the server. This affects the  system status led at the top right corner of the app frontend.