AMNES Development Environment

Developing and working on a project like AMNES requires you to setup a debug environment to test your new changes to the codebase. As a typical AMNES setup consists of multiple components like a controller, multiple workers and additional services, this will become a bottleneck for development workflow.

To provide a replicable debugging environment with as less configuration and management effort aspossible, the AMNES Development Utility provides commands, scripts, configurations and assets for a Debug Environment based on Docker and Docker-Compose.

Prerequirements

Before starting to use the Debug Environment, you need to configure your system. Besides a copy of the AMNES repository, you need a working Pipenv-Environment as well as amnes and amnesdev already installed.

Please make sure that you read and followed the steps mentioned in Introduction to AMNES Development correctly.

In addition to that, you need a running Docker Daemon (Docker Engine) on your local system and the Docker-Compose utility already installed.

The installation and configuration of Docker and its additional tools are out of the scope of this document. For further instructions on how to install Docker and Docker Compose, please consult the official documentation:

• Install Docker
• Install Docker Compose

It is recommended to add your user to the docker user group, so you are able to execute docker and docker-compose commands without using sudo as a prefix.

We recommend the following /etc/docker/daemon.json configuration:

{
    "userland-proxy": false,
    "bip": "172.29.0.1/24",
    "fixed-cidr": "172.29.0.1/24",
    "fixed-cidr-v6": "fddc::/64",
    "storage-driver": "overlay2",
}

Structure of Development Environment

AMNES Dev. Environment is based on Docker Containers and Docker Bridge Networks which are combined and managed by Docker-Compose. After spawning an AMNES Debug Session you can interact with all components from your host system. In addition to that, you can also start all containers in debug mode so you can debug them remotely from whithin your IDE.

Docker Images and Environment Variants

To use this Development Environment, you need AMNES as a packaged docker container image. For basic testing of configurations, you can use the current version of the main branch develop by using the official AMNES Docker Images. If you want to run and debug your local version of AMNES, you need to build your own containers locally.

The following commands and sections refer to following image tags or variants:

• develop: Official Docker Images for main branch.
• local: Locally built docker images with own AMNES sources.
• debug: Locally built docker images with own AMNES sources and additional debug utilities.

It is possible to patch all docker images by creating the file dev/support/docker/images/patch/Dockerfile using the following template:

# Patch local AMNES Image (and debug AMNES Image)
FROM dev/amnes:local

# Custom Content

If the file exists, the rebuild command will ask you if you want to patch the docker images. You can pass the --patch parameter to the command to skip the confirmation prompt with Yes.

The different environment configurations are named as their used images.

Working with Development Environments

If you do not want to use pre-built docker images of the develop branch, you need to build them locally by using AMNES Development Utility.

amnesdev docker rebuilt [TAG]

If you do not pass a tag, it will implicitly use all as an argument and it will build all available image tags:

• dev/amnes:local
• dev/amnes:debug

You can run single rebuilds for local or debug but keep in mind, that rebuilding debug will use your current dev/amnes:local image as a base.

After building (or pulling) all docker images, you can spawn an environment by calling:

amnesdev docker env [VARIANT] -- [ARGS]

With variant you can specify which docker images should be used and all arguments after the double-dashes will be directly passed to docker-compose. Here are a few example commands for the local variant:

• Spawn and attach to all containers: amnesdev docker env local -- up
• Spawn everything in background: amnesdev docker env local -- up -d
• Attach to all containers: amnesdev docker env local -- logs -f -t
• Stop all containers: amnesdev docker env local -- stop
• Stop and remove everything: amnesdev docker env local -- down

There exists a shortcut command:

• amnesdev debug run: Rebuilds all image tags and calls up for debug variant.
• amnesdev debug cleanup: Calls down for debug variant.

For more information see amnesdev docker --help and amnesdev debug --help.

Debug Images and Docker Networks

If containers based on debug images are started, AMNES components are not executed immediately as AMNES is executed by PTSVD which opens port 5678 on the container's management network address. You need to attach to every component with a ptvsd-client (you can directly disconnect) to start the execution.

If you use Visual Studio Code, you can use the provided launch configurations. See AMNES Development Utility for more information.

You can directly attach to any of the debug sessions for debugging. See docker compose scripts in dev/support/docker/compose for all management network addresses.