In this example you will learn:
- How to upload a Program.
- How to run a Program.
An example of the finished Scenario Plan can be found here: (Tutorial) A simple Program
In order to upload a Program, you need to install Docker.
Docker is used by the lod-tools to compile your Program and upload it, so Docker must be installed and running on your local system.
About Elody and Docker
Docker is a very popular tool for safely packaging software. It enables you to make software run on any platform, regardless of OS or dependencies.
All programs on Elody are wrapped in a Docker Image. Elody uses Rules and Options to determine what Programs to run, but once a Program runs it is all up to the Docker Container.
In other words: Programs encapsulated in Docker Containers are used to solve problems, Rules and Options are used to choose which Programs to run.
More details about integrating programs can be found in the documentation.
You can execute a Program as an action like this:
Just define an action of type 'execute_program' and specify the 'name' of the Program. If you are implementing this tutorial as you are reading it, remember that you will need to name your own Program something different, since Program names on Elody must be unique.
Let's define the Program we want to upload. Our example Program will be very simple: It just prints the typical "Hello World!" Message.
The examples in this tutorial use Programs written in Python.
The Program needs to have a way to communicate with Elody, so that it can know what has already happened in the Scenario so far, and so that it can tell Elody what to do. Elody provides libraries that can be installed inside a Docker Image to make this straightforward.
To define our Program, we create a folder with the following 4 files in it (each tab is a file):
Here is what each file does:
- DESCRIPTION.txt is a textual description of the Program. It is used as the public documentation of the Program, which can be found here.
- app.py is the program itself and contains Python code. We only do a few things here:
- We import the lod library, which is Elody's library for communicating with Python programs in Docker. The documentation of the lod library can be found here.
- We create a Message to the user. Because Messages can have several components, this uses method chaining: First we create an empty Message object with
lod.start_message(), then we add two message_components of type 'text' with
add_text(), then we finish the Message with
- We wrap our code in a lod_manager. This makes the output available to Elody and also helps with debugging, as we will see later in this tutorial.
- Dockerfile is the file that tells Docker how to use the program. You can find detailed documentation about Dockerfiles on the internet. This Dockerfile is a basic Dockerfile for Python programs. It does the following:
- Base the entire Docker Image on a Python 3.6 base image.
- Install all Python libraries mentioned in requirements.txt.
- Copy the files from the folder the Dockerfile is in into the Docker Image.
- Declare app.py as the starting point of our Docker Container.
- requirements.txt lists all Python libraries used by our Program. Since this is just a Hello World example, the only required library is 'lod', to communicate with Elody.
Uploading the Program
We can upload the Program with:
lod-tools upload-program -n "The_name_of_my_program" -f "/path/to/a/folder/containing/the/program" -r
Note that this uploads the program as a release version, since we used the '-r' option. If you don't use the '-r' option, the Program is uploaded as a developer version, and Scenario Plans will ignore it unless you explicitly state otherwise. This is explained in more detail later in the tutorial.
At this stage, our simple Scenario Plan, (Tutorial) A simple Program, should be able to call the Program and print "Hello World!".