The ideal development environment is a recent Linux system, or similar Unix based system such as MacOSX. Some pieces of the project are strictly geared towards RPM packaging, and therefore an RPM based system such as Redhat or Fedora would be ideal.
This guide assumes that you will be working out of a virtualenv root. As the project involves multiple services, it is best practice to work out of a few separate terminals. We will reference terminals as their associated piece of the project. For example, ‘Hub Terminal’ or ‘Client Terminal’. All terminals are assumed to be on the same system but this is not necessary.
We assume the virtualenv root to be ‘~/env/mf/’ but it can be anything.
Hub Terminal:
$ virtualenv --no-site-packages ~/env/mf/
$ source ~/env/mf/bin/activate
After activating a virtualenv, you will see the name of the virtualenv prefix your shell:
(mf) $
Note that anytime you are working with MonkeyFarm, either installing python modules, or using the application... you must have the virtualenv active.
Hub Terminal:
(mf) $ cd /path/to/monkeyfarm/src/monkeyfarm.hub/
(mf) $ python setup.py develop
(mf) $ cp -a dev.ini-example dev.ini
(mf) $ paster setup-app dev.ini
The bootstrap script spits out three default api keys. These are the same every time you run ‘setup-app’. You will need these when configuring other services below. At this point you should be able to run the hub.
(mf) $ paster serve --reload dev.ini
By default the monkeyfarm.hub uses a sqlite database at devdata.db, and listens on the localhost port 8080. You should be able to hit the application at:
At this point you will need to switch to a new terminal while the hub runs in this one.
The client relies on monkeyfarm.core, and monkeyfarm.interface, so will install those here as well.
Client Terminal:
(mf) $ cd /path/to/monkeyfarm/src/interfaces/python/
(mf) $ python setup.py develop
(mf) $ cd /path/to/monkeyfarm/src/monkeyfarm.core/
(mf) $ python setup.py develop
(mf) $ cd /path/to/monkeyfarm/src/monkeyfarm.client/
(mf) $ python setup.py develop
(mf) $ cp -a /path/to/monkeyfarm/src/monkeyrfarm.core/config/mf.conf-dev ~/.mf.conf
At this point you want to look at ~/.mf.conf and edit any settings that might not match your environment. Specifically:
datadir tmpdir workdir cachedir plugin_config_dir log_file mf_hub_baseurl api_key
The api_key should be that of the user ‘mf-admin’, or can be for any user you register in the future. At this point you should be able to run the client without issues:
(mf) $ mf --help
The regulator also relies on monkeyfarm.core and monkeyfarm.interface but those should already be installed.
Regulator Terminal:
(mf) $ cd /path/to/monkeyfarm/src/monkeyfarm.regulator/
(mf) $ python setup.py develop
In production, the regulator has its own config. However in development you can either append the config to ~/.mf.conf or to put a config file under the plugin_config_dir. It’s easiest to append it to your personal config:
(mf) $ cat /path/to/monkeyfarm/src/monkeyfarm.regulator/config/mf-regulatord.conf >> ~/.mf.conf
You then need to modify any settings in ~/.mf.conf under the ‘[regulator]’ section. Specifically the setting for ‘api_key’. This should be set to the default api_key for the ‘mf-system’ user as obtained from the ‘setup-app’ process above.
You should now be able to run the regulator daemon:
(mf) $ mf-regulatord --debug
You will now want to switch to another terminal to setup the worker.
The worker also relies on monkeyfarm.core and monkeyfarm.interface but those should already be installed.
Worker Terminal:
(mf) $ cd /path/to/monkeyfarm/src/monkeyfarm.worker/
(mf) $ python setup.py develop
Again, in production the worker has its own config. However in development you can either append the config to ~/.mf.conf or to put a config file under the plugin_config_dir. It’s easiest to append it to your personal config:
(mf) $ cat /path/to/monkeyfarm/src/monkeyfarm.worker/config/mf-workerd.conf >> ~/.mf.conf
You then need to modify any settings in ~/.mf.conf under the ‘[worker]’ section. Specifically the setting for ‘api_key’. This should be set to the default api_key for the ‘mf-system’ user as obtained from the ‘setup-app’ process above.
You should now be able to run the worker daemon:
(mf) $ mf-workerd --debug
You will now want to switch back to the Client Terminal, or install additional plugins.
MonkeyFarm has a number of core/builtin plugins that extend certain functionality. In general, plugins provide ‘handlers’ that enable the system to interact with external service and or provide certain abilities. For example, the monkeyfarm.generic_build plugin provides a generic build handler that can be used for generic builds (it just calls ./mf-build). The monkeyfarm.mock plugin provides a build handler that runs builds using the Fedora Mock utility (for building RPMs). Every plugin is different. What should be noted however is that when installing plugins that provide handlers, the regulator and/or worker services need to be restarted in order to register those handlers (depending on what that plugin provides).
The following is an example of installing the monkeyfarm.git plugin which provides a vcs_handler called ‘git’:
(mf) $ cd /path/to/monkeyfarm/src/plugins/monkeyfarm.git
(mf) $ python setup.py develop
(mf) $ cat config/plugins.d/git.conf >> ~/.mf.conf
You then need to restart the regulator daemon. The monkeyfarm.git plugin config looks like:
# Git VCS Plugin Configurations
# ---
# This is meant to be a system wide git vcs handler. If different projects
# have altering git servers/repository url templates, then you may need to
# write a vcs handler plugin for each project.
[git]
enable_plugin = true
provider = mf
# Path to git binary
vcs_bin_path = /usr/bin/git
# Repository URL template. This is meant to be a generic, work-for-all
# packages URL. If it does not, you may want to consider writing your own
# vcs handler plugin. The following vars are substituted:
#
# @MF_PROJECT_LABEL@
# @MF_PACKAGE_LABEL@
#
vcs_url_template = git@example.com/@MF_PACKAGE_LABEL@.git
# Branch to checkout/pull from
branch = master
This plugin allows MonkeyFarm to pull from a Git repo for builds.