Improve This Doc

Plugin creation

A plugin can be a simple implementation of triggers or can implement a command structure of its own. Dokku has no restrictions on the language in which a plugin is implemented; it only cares that the plugin implements the appropriate commands or triggers for the API. NOTE: any file that implements triggers or uses the command API must be executable.

If you create your own plugin:

  1. Take a look at the plugins shipped with Dokku and hack away!
  2. Check out the list of triggers your plugin can implement
  3. Upload your plugin to GitHub with a repository name following the dokku-<name> convention (e.g. dokku-mariadb)
  4. Edit this page and add a link to your plugin
  5. Subscribe to the dokku development blog to be notified about API changes and releases

Compilable plugins (Golang, Java(?), C, etc.)

When developing a plugin, you must implement the install trigger such that it outputs the built executable(s) using a directory structure that implements the plugin's desired command and/or triggers the API. See the smoke-test-plugin for an example.

Command API

There are 3 main integration points: commands, subcommands/default, and subcommands/<command-name>.

commands

Primarily used to supply the plugin's usage/help output. (i.e. plugin help).

subcommands/default

Implements the plugin's default command behavior. (i.e. dokku plugin).

subcommands/<command-name>

Implements the additional command interface and will translate to dokku plugin:cmd on the command line. (i.e. dokku plugin:install).

Sample plugin

The below plugin is a dummy dokku hello plugin.

hello/subcommands/default

#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"

hello_main_cmd() {
  declare desc="prints Hello \$APP"
  local cmd="hello"
  # Support --app/$DOKKU_APP_NAME flag
  # Use the following lines to reorder args into "$cmd $DOKKU_APP_NAME $@""
  local argv=("$@")
  [[ ${argv[0]} == "$cmd" ]] && shift 1
  [[ -n $DOKKU_APP_NAME ]] && set -- $DOKKU_APP_NAME $@
  set -- $cmd $@
  ##

  [[ -z $2 ]] && dokku_log_fail "Please specify an app to run the command on"
  verify_app_name "$2"
  local APP="$2";

  echo "Hello $APP"
}

hello_main_cmd "$@"

hello/subcommands/world

#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"

hello_world_cmd() {
  declare desc="prints Hello World"
  local cmd="hello:world"
  # Support --app/$DOKKU_APP_NAME flag
  # Use the following lines to reorder args into "$cmd $DOKKU_APP_NAME $@""
  local argv=("$@")
  [[ ${argv[0]} == "$cmd" ]] && shift 1
  [[ -n $DOKKU_APP_NAME ]] && set -- $DOKKU_APP_NAME $@
  set -- $cmd $@
  ##

  [[ -z $2 ]] && dokku_log_fail "Please specify an app to run the command on"
  verify_app_name "$2"
  local APP="$2";

  echo "Hello world"
}

hello_world_cmd "$@"

hello/commands

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

case "$1" in
  help | hello:help)
    help_content_func () {
      declare desc="return help_content string"
      cat<<help_content
    hello <app>, Says "Hello <app>"
    hello:world, Says "Hello world"
help_content
    }

    if [[ $1 = "hello:help" ]] ; then
        echo -e 'Usage: dokku hello[:world] [<app>]'
        echo ''
        echo 'Say Hello World.'
        echo ''
        echo 'Example:'
        echo ''
        echo '$ dokku hello:world'
        echo 'Hello world'
        echo ''
        echo 'Additional commands:'
        help_content_func | sort | column -c2 -t -s,
    else
        help_content_func
    fi
    ;;

  *)
    exit $DOKKU_NOT_IMPLEMENTED_EXIT
    ;;

esac

Each plugin requires a plugin.toml descriptor file with the following required fields:

[plugin]
description = "dokku hello plugin"
version = "0.1.0"
[plugin.config]

A few notes:

  • Remember to chmod +x your executable files

  • Always support DOKKU_TRACE as per the 2nd line of the above example

  • If your command depends on an application, include a check for whether that application exists (see the above example)

  • You must implement a help command, though you may leave it empty. Also, you must use commas (,) in the command syntax to support output in columns

  • Commands should be namespaced

  • As of 0.3.3, a catch-all should be implemented that exits with a DOKKU_NOT_IMPLEMENTED_EXIT code. This allows Dokku to output a command not found message.

  • Consider whether you want to include the set -eo pipefail option. Look at the following example :

    IMAGE=$(docker images | grep "user/repo" | awk '{print $3}')
    if [[ -z $IMAGE ]]; then
        dokku_log_fail "user/repo image not found... Did you run 'dokku plugin:install'?"
    fi

    If user/repo doesn't exist, Dokku exits just before the awk command and the dokku_log_fail message will never go to STDOUT. printed with echo. You would want to use set -e in this case.

    Here is the help entry for set:

    help set
      Options:
        -e  Exit immediately if a command exits with a non-zero status.
        -o option-name
            pipefail     the return value of a pipeline is the status of
                         the last command to exit with a non-zero status,
                         or zero if no command exited with a non-zero status
    
  • In the case that your plugin needs to set application configuration settings and you want to avoid having to restart (default Heroku-style behavior) these "internal" commands provide this functionality:

    dokku config:set --no-restart node-js-app KEY1=VALUE1 [KEY2=VALUE2 ...]
    dokku config:unset --no-restart node-js-app KEY1 [KEY2 ...]
  • If you want to allow other plugins access to (some of) your plugin's functionality, you can expose this by including a functions file in your plugin for others to source

    • You should consider all functions in that file to be publicly accessible by other plugins
    • Any functions you want to keep private should reside in your plugin's trigger/ or commands/ directories
  • As of 0.4.0, Dokku allows image tagging and deployment of tagged images

    • This means hard-coding the $IMAGE as dokku/$APP is no longer sufficient
    • You should now use get_running_image_tag() and get_app_image_name() as sourced from common/functions (see the plugin triggers doc for examples). Note: This is only for plugins that are not pre/post-build-* plugins
  • As of 0.5.0, we use container labels to help cleanup intermediate containers with `dokku cleanup

    • This means that if you manually call docker run, you should include $DOKKU_GLOBAL_RUN_ARGS to ensure your intermediate containers are labeled correctly
  • As of 0.6.0, you should not not call the dokku binary directly from within plugins because clients using the --app argument are potentially broken when doing so (as well as other issues)

    • You should instead source the functions file for a given plugin when attempting to call Dokku internal functions
  v: master
Versions
On GitHub
View
Edit

Free document hosting provided by Viewdocs.