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, thebeat
tool is now functional. - To build this documentation locally, use the
sphinx-build
tool inbin/
:./bin/sphinx-build doc/ sphinx/
to output tosphinx/
.
Running the BEAT Platform locally¶
- Build the BEAT web environment locally.
- Build
beat.web
using the Python environment built frombeat.env.web
. - Install the example environment in
beat.web
via./bin/django install
. - Run
./bin/django runserver
and go tolocalhost:8000/
to see if it works. The default example login isuser
with passworduser
.
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
.