- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with circus
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
Circus is a process and socket manager by Mozilla. Its goal is similar to other tools like Supervisord, runit, god etc. It is built on a much more modern and scalable foundation powered by ZeroMQ.
This module will install Circus for you. This entails installing the necessary packages, creating the configuration directories and writing the main circusd.ini to get you started.
Because there currently aren't any packages to install Circus from we rely on
pip
to do the heavy lifting for us.
We also ship with Upstart, systemd and Sys-V startup scripts which are taken directly from Mozilla's source code repository. Any issues with the startup scripts should be raised with Mozilla.
- Install circus from PyPi;
- Create
/etc/circus
,/etc/circus/conf.d
; - Create
/etc/circus/circusd.ini
; - Symlink
/usr/local/bin/circusd
into/usr/bin
(only done if installed from pip to ensure the init-scripts can start the daemon).
Python and Pip must be available for this module to be able to work.
To install circus:
include ::circus
In order to install Circus you'll need the Python development headers installed on your system and a few other things. If they aren't managed anywhere yet this module can do that for you.
class { 'circus':
package_circus_dependencies => ['python-dev', 'build-essential'],
}
You can also use Hiera with databindings to do the same thing.
include ::circus
---
circus::package_circus_dependencies:
- 'python-dev'
- 'build-essential'
Because Circus is still relatively new and packages are bound to pop up at some point in time you might want to switch to those instead. To make this possible a few variables have been defined:
package_circus
: defaults tocircus
;package_circus_provider
: defaults topip
, set toundef
to let Puppet figure out which one to use on your platform;package_circus_dependencies
: List of dependent packages not available from PyPi;
package_ensure
: in what state we want Circus- default:
installed
- option: valid values for the package type's ensure attributed except for
held
andpurged
- type: string
- default:
package_circus
: name of the Circus package- default:
circus
- option: whatever works for you
- type: string
- default:
package_circus_provider
: what provider to use to install Circus- default:
pip
- option: any valid provider for the package type, use
undef
to use your platforms default - type: string
- default:
package_circus_dependencies
: additional dependencies to install- default:
[]
- option: an array of package names
- type: array of strings
- default:
service_circus_provider
: init-system to configure- default:
sysv
- option:
sysv
,upstart,
systemd` - type: string
- default:
conf_prefix
: where to create the Circus configuration directory- default:
/etc
- option any absolute path
- type: string that validates as an absolute path
- default:
log_prefix
: where to create the Circus logging directory- default:
/var/log
- option: any aboslute path
- type: string that validates as an absolute path
- default:
logrotate_dir
: where to install the logrotate configuration- default:
/etc/logrotate.d
- option: any aboslute path
- type: string that validates as an absolute path
- default:
Though you can call these classes individually they are considered private and
depend on variables set in the main circus
class.
circus::install
: installs Circus;circus::configure
: writes configuration files for Circus;circus::services
: starts and manages the Circus daemon.
This module requires Puppet 3. We test on the full set of supported Rubies but only the latest Puppet version. Since this module does not rely on any fact we do not explicitly test against mutliple Facter versions.
It should work on most Linux platforms. BSD's are currently missing rc-scripts and probably a few other things but support should be trivial to add.
Windows is not supported.
This module is hosted on Github, that is where all development takes place. Feel free to fork the module and send pull requests for the enhancements you want to merge.
When you change something or add something new you are expected to:
- provide a rationale for the change ('because it suits me better is not a good reason');
- modify or add tests for the new behaviour.