The program lod-tools is a tool that can be used by developers to interact with the Elody server.
It is used to upload Programs and Rules, as well as for testing.
Installation and Configuration
lod-tools is written for Python 3 and can be installed with pip.
If you don't have pip, install it by following the instructions here.
Install lod-tools by running this command:
pip install lod-tools
After installing lod-tools, you should configure it with your login details so that you don't have to enter these every time you use the program.
lod-tools configure -e your_login_email_here -p your_login_password_here
Additionally, you will also need to install Docker to be able to upload your own Programs. You can do this here.
Verify it works
If you want to verify that both lod-tools and Docker are installed correctly, create a new folder and run the following commands in it:
lod-tools generate-example-program -f ExampleProgram
lod-tools generate-example-input-folder -f ExampleProgramInput
lod-tools test-program-offline -p ExampleProgram -prep ExampleProgramInput -e ExampleExecutionFolder
This compiles and executes the Program introduced in the Demo Tutorial on example data. If these commands all complete successfully, the folder ExampleExecutionFolder should contain several files: The two files from the ExampleProgramInput folder, a log file, and two additional output files that were generated by the program.
You can access the help menu by running
You can use the following command to create several Symbols at once:
lod-tools create-symbols -f "/path/to/a/file/describing/the/symbols.txt"
To use this, you must have defined your Symbols in a text file as shown in the tutorial.
You can use this to create Symbols, or to update the descriptions of your existing Symbols.
Uploading a Rule
You can use the following command to upload a Rule:
lod-tools upload-rule -f "/path/to/a/file/describing/the/rule.txt"
To use this, you must have defined your Rule in a text file. The name of the rule will be set to the 'name' field in the file. If there is no such field, the filename is used instead.
If the Rule should depend on dynamically generated Symbols created by a create-symbols command, use the '-s' option to use the file generated by create-symbols.
If you use the '-d' flag, you can instruct the server to deactivate any previously uploaded Rules of the same name, which is especially useful if you are testing things and frequently making changes.
Uploading a Program
You can use the following command to upload a Program:
lod-tools upload-program -n "The_name_of_my_program" -f "/path/to/a/folder/containing/the/program"
Uploading a Program with the same name again does not delete older versions. However, since Programs (unlike Rules) only run when they are made to be run, and can't decide to run on their own, this is not harmful. If a Rule refers to a Program by name instead of ID, it always selects the newest version of the Program.
When you run the upload-program command, lod-tools looks for a Dockerfile in the selected folder and compiles the Image. It then pushes that Image to the Elody server.
In principle, Any Docker Image is a valid program to upload. Of course, if the uploaded Image does not behave in the way Elody expects it to work, then it will simply result in an error. Elody will ignore crashed programs and try something else without letting the user know about it, though you can still notice it by inspecting the Scenario in Developer Mode [This is not the case during the Beta test: any crashes will result in an easily visible error message to make debugging easier].
A library called 'lod' is available for python via pip, which makes it very easy to adapt an existing python program to work with Elody. You can use the following commands to create an example program and to test your program offline:
lod-tools generate-example-program --help
lod-tools generate-example-input-folder --help
lod-tools test-program-offline --help
You can choose any license you want for the programs you upload, so long as you agree to the Software License Agreement for Contributors. In particular, you may upload your code as OpenSource, or you may forbid anyone else from using or modifying it.
lod-tools upload-program has an option to upload the source code of your program, so that it is available for other users to inspect with
lod-tools download-program. This option is on by default, and highly recommended: If other developers can't inspect your code, they can not verify that you did not make a mistake or even deliberately put malware in it. You should also be aware that users are free to download any Docker Images you upload and that Docker Images can be inspected from the outside.
By uploading a program, you grant us the right to use it. You may only upload programs you own or that are available under a license that permits us to use them.
There is a minor known security flaw here: It is currently possible to upload source code that does not actually match the content of the Docker Image. You can use
docker run -it image_name sh to inspect an Image's content, but this too could be fooled by a dedicated enough hacker.
We are considering several ways of addressing this problem and will have it fixed by the end of the Beta. Until then, abusing this security flaw is a bannable offense.