Johann

Johann is a lightweight and flexible “scenario orchestrator”. It makes it easy to coordinate the actions of groups of computers into cohesive, reconfigurable scenarios. It’s sort of like the conductor for an orchestra of computers, and you get to write the music.

Summary

• Requirements
• Usage
• This is an alpha prototype
• Roadmap
• Contributing
• Built With
• License
• Acknowledgments

Requirements

Johann is designed to be used on Linux. It has been tested on Ubuntu 18.04, and likely works on several other distributions as well.

Johann requires the following to run:

• Docker Engine
• Docker Compose
• Make

Here is an example of how to install these on Ubuntu/Debian:

# Install make
sudo apt-get update
sudo apt-get install build-essential

# Install docker via convenience script (not for production environments)
curl https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# log out and log back in
docker run hello-world

# Install docker-compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

Usage

Start Johann (this will also build it). This can take a while the first time.

make up

This is an alpha prototype

Johann is an evolutionary prototype in its initial development. It is not yet feature complete, and breaking changes can happen at any time. This is represented by its major version zero (0.y.z).

For now, Johann should be considered to be in perpetual alpha. This is made explicit by the "a" in the version identifier. Please expect it to be rough around the edges (and maybe everywhere else).

Johann should only be used in isolated or protected networks of known and trusted hosts/users. It should only be used for research and development, and not in production.

Roadmap

Here are some planned improvements to Johann, in no particular order:

• add a simple GUI
• switch to pydantic
• switch to fastapi
• add more documentation
• use mypy and pylint
• add more tests
• add user authentication
• support kwargs in Measures
• Score-level variables; configurable at runtime

Contributing

We welcome pull requests! Before starting, please communicate with us to discuss what you would like to change. Please also update tests and documentation as appropriate. Thanks!

Getting Started

Install development packages.

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3-dev python3-venv build-essential git

# Alpine (not officially supported)
apk add --no-cache python3-dev bash make git gcc linux-headers musl-dev

Setup the virtual environment used for Johann development. This also installs pre-commit hooks.

make dev-setup

Development Usage

Start Johann in development mode (this will also build it).

make dev

Testing

make test

Linting

Johann uses pre-commit. For the list of hooks used, see .pre-commit-config.yaml.

Lint the files staged for commit.

make lint

Lint all files in the repo.

make lint-all

Use safety to check for known dependency vulnerabilities.

make safety

Built With

In addition to the dependencies listed in Requirements, please see:

• setup.py
• requirements-dev.in
• .pre-commit-config.yaml

In addition to these, Johann is also made possible with the help of (alphabetically):

• gitlab-ci
• pmtr

License

Use of this source code is governed by a BSD-3-clause license that can be found in the LICENSE file. See the AUTHORS file for names of contributors.

Acknowledgments

• JHU/APL for supporting Johann's licensing as open source
• Johann S.D.G.