Introduction

Kliko is a specification, validator and parser for the Scientific Compute Container specification. Kliko is written in Python.

This documentation is intended for the developer who wants to package up a piece of software into a Kliko container.

Installation

Development of Kliko is done on github. You can install Kliko inside a docker container or just on your system:

$ python setup.py install

or from pypi:

$ pip install kliko

Why Kliko?

Kliko was born out of our needs to have a more formal and uniform way of scheduling batch compute tasks on arbitrary public and private cloud platforms. Docker is perfect for encapsulating and distributing software, but the input output flow is not defined. Kliko is an attempt to create a standard way to define compute input, output and parameters.

Kliko assumes your problem looks like this:

_images/kliko.png

Kliko containers can be chained up in a sequence, for example using Luigi. An other use case is to simplify the parameterized scheduling of compute tasks using RODRIGUES.

Getting started

Creating a Kliko container

  • Create a Docker container from your application
  • Create a script /kliko in the container that can parse and use a /parameters.json file.
  • Add a kliko.yml file to the root of the container which defines the valid fields in the parameters file.
  • You can validate your kliko file with the kliko-validate script installed by the kliko Python library.

Running a kliko container

You can run a kliko container in various ways. The most simple way is to use the kliko-run script which is installed on your system when you install Kliko. Use kliko-run <image-name> --help to see a list of accepted parameters.

If you already have a parameters file you can also run the container manually:

$ docker run -v $(pwd)/parameters.json:/parameters.join:ro -v $(pwd)/input:/input:ro -v $(pwd)/output:/output:rw <image-name> /kliko

Finally you can also run kliko images and visualise results using RODRIGUES, a web based kliko runner.

Contributing

Contributions are more than welcome! If you experience any problems let us know in the bug tracker. We accept patches in the form of github pull requests. Please make sure your code works with python 2 and python3, and is pep8 compatible. Also make sure the test suit actually passes all tests. We use docker in some of the tests so you need to have that installed and configured.

Testing

Note that before you run the test suite you have to create a klikotest docker image by running make in the examples folder.