Walkthrough

This page gives an overview on setting up an environment to develop BEAT experiments locally. The topics covered are the following:

  • Preparing a proper Python environment
  • Bootstrapping beat.cmdline
  • Running the BEAT web platform locally
  • Detailing an example workflow for BEAT development

Tips for preparing a proper environment

  • Using a Conda environment is recommended.
  • beat.cmdline requires Python 2.7 and will not work on Python 3.x.
  • It uses Buildout, to bootstrap, commonly known as zc.buildout. This package is also available on Conda.
  • The Python 2.7 environment used for bootstrapping will also be the environment used to execute BEAT code when using the local executor.
  • While you can bootstrap and use beat.cmdline without having a local BEAT instance, beat can’t yet create BEAT objects (experiments, etc.) from scratch. We recommend you instead modify existing BEAT objects.
  • Running experiments using the Docker executor requires Docker to be set up locally and several docker containers.

Boostrapping beat.cmdline

Thanks to Buildout, setup is simple:

  • Clone the beat.cmdline repository.
  • Using a compatible environment (see above) run buildout in the project’s root directory. Assuming this step is successful, the beat tool is now functional.
  • To build this documentation locally, use the sphinx-build tool in bin/: ./bin/sphinx-build doc/ sphinx/ to output to sphinx/.

Running the BEAT Platform locally

  • Build the BEAT web environment locally.
  • Build beat.web using the Python environment built from beat.env.web.
  • Install the example environment in beat.web via ./bin/django install.
  • Run ./bin/django runserver and go to localhost:8000/ to see if it works. The default example login is user with password user.

An example workflow

First, have beat.web running locally. To interact with the local instance through beat.cmdline, set the platform config option through beat to http://localhost:8000/: beat set platform 'http://localhost:8080/'.

Pull example experiments from the platform via the beat tool: beat exp pull user/single/1. Run the example experiment using the local executor: beat exp run user/single/1/single to make sure one works.

Fork the single experiment, using the same user/single/1 toolchain: beat exp fork user/single/1/single user/single/1/single_test. Run the new experiment to make sure the fork works: beat exp run user/single/1/single_test. Feel free to edit the single_test JSON file to change the experiment.

Likewise, you can fork other BEAT objects (algorithms, databases, toolchains, etc.).

To see if your new BEAT objects will run on the BEAT platform, try to run using the Docker executor (which will use the BEAT docker images it can find): beat exp run --docker user/single/1/single_test.

If it works, you can push it to your BEAT platform to have it on your BEAT platform instance: beat exp push.