Plugin Reference

A Junebug plugin is a class that has specific methods that get called during specific events that happen within Junebug. Plugins provide a way to hook into Junebug and add extra functionality.

Installing plugins

The CLI and config references describe how you can add plugins to Junebug.

Methods

The following methods are available to plugins to perform actions according to events that happen within Junebug:

class junebug.plugin.JunebugPlugin

Base class for all Junebug plugins

channel_started(channel)

Called whenever a channel is started. Should be implemented by the plugin. Can return a deferred.

Parameters:channel (Channel) – The channel that has been started.
channel_stopped(channel)

Called whenever a channel is stopped. Should be implemented by the plugin. Can return a deferred.

Parameters:channel (Channel) – The channel that has been stopped.
start_plugin(config, junebug_config)

Can be overridden with any required startup code for the plugin. Can return a deferred.

Parameters:
  • config (dictionary) – The config specific to the plugin.
  • junebug_config (JunebugConfig) – The config that Junebug was started with.
stop_plugin()

Can be overridden with any required shutdown code for the plugin. Can return a deferred.

Creating Plugins

In order to create a plugin, create a python class that inherits from junebug.plugin.JunebugPlugin, and implements any of the methods. Then add the plugin to Junebug through either the CLI or a config file, as described in Installing plugins.

Bundled plugins

Nginx

Maintains configuration for an nginx virtual host for Junebug to expose http-based channels, reloading nginx whenever a new http-based channel is added.

The plugin looks for web_path and web_port config fields in each channel config given to POST /channels/. web_port determines the internal tcp port for the server that nginx should proxy requests to. web_path determines the path to expose the http-channel on (e.g. '/foo/bar') for the vhost.

The plugin will also look for a public_http object in each added channel’s config. public_http.web_path and public_http.web_port override web_path and web_port respectively. Additionally, one can disable the plugin for a particular channel by setting public_http.enabled to false.

Config options:

vhost_file:
 

The file to write the junebug nginx vhost file to

type: str
default: '/etc/nginx/sites-enabled/junebug.conf'
locations_dir:
 

The directory to write location block config files to

type: str
default: '/etc/nginx/includes/junebug/'
server_name:
 

Server name to use for nginx vhost

type: str
default: None
vhost_template:
 

Path to the template file to use for the vhost config

type: str
default: '/home/docs/checkouts/readthedocs.org/user_builds/junebug/envs/latest/local/lib/python2.7/site-packages/junebug-0.1.11-py2.7.egg/junebug/plugins/nginx/vhost.template'
location_template:
 

Path to the template file to use for each channel’s location config

type: str
default: '/home/docs/checkouts/readthedocs.org/user_builds/junebug/envs/latest/local/lib/python2.7/site-packages/junebug-0.1.11-py2.7.egg/junebug/plugins/nginx/location.template'

Note

The plugin needs permissions to write the vhost and location config files it maintains. See the config options for the default paths that the plugin will write these files to.