dokku/docs/plugins.md

Plugins

Dokku itself is built out of plugins and uses pluginhook for its plugin system. In essence a plugin is a collection of scripts that will be run based on naming convention.

Let's take a quick look at the current dokku nginx plugin that's shipped with dokku by default.

nginx-vhosts/
├── commands     # contains additional commands
├── install      # runs on dokku installation
└── post-deploy  # runs after an app is deployed

Installing a plugin

cd /var/lib/dokku/plugins
git clone <git url>
dokku plugins-install

todo: add a command to dokku to install a plugin, given a git repository dokku plugin:install <git url>?

Creating your own plugin

If you create your own plugin:

1. take a look at the plugins shipped with dokku and hack away!
2. upload your plugin to github with a repository name in form of dokku-<name> (e.g. dokku-mariadb)
3. edit this page and add a link to it below!
4. subscribe to the dokku development blog to be notified about API changes and releases

Sample plugin

The below plugin is a dummy dokku hello plugin. If your plugin exposes commands, this is a good template for your commands file:

#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x

case "$1" in
  hello)
    [[ -z $2 ]] && echo "Please specify an app to run the command on" && exit 1
    [[ ! -d "$DOKKU_ROOT/$2" ]] && echo "App $2 does not exist" && exit 1
    APP="$2";

    echo "Hello $APP"
    ;;

  hello:world)
    echo "Hello world"
    ;;

  help)
    cat && cat<<EOF
    hello <app>                                     Says "Hello <app>"
    hello:world                                     Says "Hello world"
EOF
    ;;

  *)
    exit $DOKKU_NOT_IMPLEMENTED_EXIT
    ;;

esac

A few notes:

• You should always support DOKKU_TRACE as specified on the 2nd line of the plugin.
• If your command requires that an application exists, ensure you check for it's existence in the manner prescribed above.
• A help command is required, though it is allowed to be empty.
• Commands should be namespaced.
• As of 0.3.3, a catch-all should be implemented which exits with a DOKKU_NOT_IMPLEMENTED_EXIT code. This allows dokku to output a command not found message.

Community plugins

Note: The following plugins have been supplied by our community and may not have been tested by dokku maintainers.

Datastores

Relational

Plugin	Author	Compatibility
MariaDB	Kloadut	Compatible with 0.2.0
MariaDB (single container)	ohardy	Compatible with 0.2.0
MySQL	hughfletcher
PostgreSQL	Kloadut	Compatible with 0.2.0
PostgreSQL	jezdez	Compatible with 0.2.0
PostgreSQL	jlachowski	IP & PORT available directly in linked app container env variables (requires link plugin)
PostgreSQL (single container)	jeffutter	This plugin creates a single postgresql container that all your apps can use. Thus only one instance of postgresql running (good for servers without a ton of memory).
PostgreSQL (single container)	ohardy	Compatible with 0.2.0
PostGIS	fermuch

Caching

Plugin	Author	Compatibility
Memcached	jezdez	Compatible with 0.2.0
Memcached	jlachowski	IP & PORT available directly in linked app container env variables (requires link plugin)
Redis	jezdez	Requires https://github.com/rlaneve/dokku-link; compatible with 0.2.0
Redis	luxifer
Redis (single container)	ohardy	Compatible with 0.2.0
Varnish	Zenedith	Varnish cache between nginx and application with base configuration

Queuing

Plugin	Author	Compatibility
RabbitMQ	jlachowski	IP & PORT available directly in linked app container env variables (requires link plugin)
RabbitMQ (single container)	jlachowski	IP & PORT available directly in linked app container env variables (requires link plugin)

Other

Plugin	Author	Compatibility
CouchDB	RaceHub	Compatible with 0.2.0
MongoDB (single container)	jeffutter
RethinkDB	stuartpb	2014-02-22: targeting dokku @ latest; will fail with Dokku earlier than 28de3ec.
RiakCS (single container)	jeffutter	Incompatible with 0.2.0 (checked at dccee02)
Neo4j	Aomitayo

Process Managers

Plugin	Author	Compatibility
Circus	apmorton
Shoreman	statianzo	Compatible with 0.2.0
Supervisord	statianzo	Compatible with 0.2.0
Logging Supervisord	sehrope	Works with dokku @ c77cbf1 - no 0.2.0 compatibility
Forego	iskandar	Compatible with 0.2.x

Dokku Features

Plugin	Author	Compatibility
app-url	mikecsh	Works with 0.2.0
Custom Domains	motin	Compatible with 0.2.*
Debug	heichblatt
Docker Direct	heichblatt
Docker Options	dyson	dokku >= c77cbf1
Dokku Name	alex-sherwin	dokku >= c77cbf1
Dokku Registry	agco-adm
git rev-parse HEAD in env	nornagon	Compatible with 0.2.0
HTTP Auth Secure Apps	matto1990	Works with v0.2.3
Host Port binding	stuartpb	dokku >= c77cbf1. 2014-02-17: a043e98 targeting dokku @ latest
Hostname	michaelshobbs
Link Containers	rlaneve	dokku >= c77cbf1
Multi-Buildpack	pauldub
Multiple Domains4	wmluke	Compatible with 0.2.0
Nginx-Alt	mikexstudios	Works with v0.2.3
Persistent Storage	dyson	Requires dokku >= c77cbf1
Ports	heichblatt
Pre-Deploy Tasks	michaelshobbs
Rebuild application	scottatron	Compatible with 0.2.x
SSH Deployment Keys2	cedricziel	2014-01-17: compatible with upstream/master
SSH Hostkeys3	cedricziel	2014-01-17: compatible with upstream/master
Supply env vars to buildpacks	cameron-martin	Works with v0.2.3
VHOSTS Custom Configuration	motin	Compatible with 0.3.1
Volume (persistent storage)	ohardy	Compatible with 0.2.0

² Adds the possibility to add SSH deployment keys to receive private hosted packages

³ Adds the ability to add custom hosts to the containers known_hosts file to be able to ssh them easily (useful with deployment keys)

⁴ Conflicts with VHOSTS Custom Configuration

⁵ On Heroku similar functionality is offered by the heroku-labs pipeline feature, which allows you to promote builds across multiple environments (staging -> production)

Other Add-ons

Plugin	Author	Compatibility
Wordpress	[abossard][]	Dokku dev, mariadb, volume, domains
Node	pnegahdar
Node	ademuk
Chef cookbooks	fgrehm
Bower install	alexanderbeletsky
Bower/Grunt	thrashr888
Bower/Gulp	gdi2290
Elasticsearch	robv
Elasticsearch	jezdez	Compatible with 0.2.0
Elasticsearch1	blag	Compatible with 0.2.0
HipChat Notifications	cef
Graphite/statsd	jlachowski
APT	F4-Group
User ACL	[Maciej Łebkowski][]
PrimeCache	darkpixel

¹ Forked from jezdez/dokku-elasticsearch-plugin: uses Elasticsearch 1.2 (instead of 0.90), doesn't depend on dokku-link, runs as elasticsearch user instead of root, and turns off multicast autodiscovery for use in a VPS environment.