Installing Captain and Shove¶
These instructions are for installing Captain and Shove in a production setup. If you want to work on Captain or Shove as a developer, see the Contributing page.
Prerequisites¶
- Python 2.6 or 2.7
- A database (or use Django’s SQLite support)
- A running instance of RabbitMQ
Setting up Shove¶
Shove installs as a normal Python package. It’s not on PyPI yet, but you can install it using pip:
pip install git+https://github.com/mozilla/shove.git#egg=shove
This should install the shove
executable into your environment, which is used to start the
Shove daemon.
Shove requires a settings file; an example settings file can be found in the Shove source code.
The SHOVE_SETTINGS_FILE
environment variable should contain an absolute file path to the
settings file you want to use.
The settings file contains details for connecting to RabbitMQ, as well as a mapping of project IDs to directories that projects are contained in. You must edit this dictionary to include file paths to any projects that you want Shove to be able to run commands for.
Setting up Captain¶
Captain is a Django project. It’s intended to be run as a WSGI application. The WSGI file for
Captain is located at captain/wsgi.py
under the repository root.
You can retrieve the code for Captain by cloning https://github.com/mozilla/captain.git
using
git.
Dependencies¶
Captain comes with almost all of its dependencies included in the vendor
directory, and
wsgi.py
automatically alters the Python import path to include them. There are a few compiled
dependencies that aren’t included: They are specified in requirements/compiled.txt
and can be
installed on your target system using pip:
pip install -r requirements/compiled.txt
Note
Alternatively, you can create system packages for the compiled requirements and have them installed via a server automation framework like Puppet.
Settings¶
Once you’ve installed the dependencies, you need to create a settings file by copying
captain/settings/local.py-dist
to captain/settings/local.py
and editing the contents:
cp captain/settings/local.py-dist captain/settings/local.py
vi captain/settings/local.py
The comments in the file and the Django settings documentation will help explain how to configure the settings for your setup.
Database¶
Next, you must initialize the database using the syncdb
and migrate
commands:
python manage.py syncdb
python manage.py migrate
Static Content¶
There are two directories that need to be served up by a static webserver alongside Captain: the
static
directory and the media
directory. static
contains all the static CSS,
JavaScript, and images for the site, while media
contains the raw logs sent back from Shove.
The filesystem paths for these directories are configured by the MEDIA_ROOT
and STATIC_ROOT
settings in the settings file, and default to being located at the root of the repositry. The
public-facing URLs for them are controlled by the MEDIA_URL
and STATIC_URL
settings, and
default to /static
and /media
.
Once you’ve configured these settings (if necessary), you must populate the static
directory by
running the following command:
python manage.py collectstatic
This should fill static
with files. Then you must use the web server of your choice to serve
these files alongside the rest of the Captain interface.
Finished!¶
After that, you should be ready to run the site via whatever WSGI-compliant web server you prefer.
Log Event Listener¶
Captain includes a command that listens for log events from Shove. After configuring Captain using the steps above, you should be able to start the process with this command:
python manage.py monitor_shove_logs
Note
You should probably use a process control system like supervisord to manage this process as well as the Shove process.