[Pluginhooks](https://github.com/progrium/pluginhook) are a good way to jack into existing dokku infrastructure. You can use them to modify the output of various dokku commands or override internal configuration.
Pluginhooks are simply scripts that are executed by the system. You can use any language you want, so long as the script:
- Is executable
- Has the proper language requirements installed
For instance, if you wanted to write a pluginhook in PHP, you would need to have `php` installed and available on the CLI prior to pluginhook invocation.
The following is an example for the `nginx-hostname` pluginhook. It reverses the hostname that is provided to nginx during deploys. If you created an executable file named `nginx-hostname` with the following code in your plugin, it would be invoked by dokku during the normal app deployment process:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
APP="$1"; SUBDOMAIN="$2"; VHOST="$3"
NEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`
echo "$NEW_SUBDOMAIN.$VHOST"
```
## Available Pluginhooks
There are a number of plugin-related pluginhooks. These can be optionally implemented by plugins and allow integration into the standard dokku plugin setup/backup/teardown process.
The following pluginhooks describe those available to a dokku installation. As well, there is an example for each pluginhook that you can use as templates for your own plugin development.
> The example pluginhook code is not guaranteed to be implemented as in within dokkku, and are merely simplified examples. Please look at the dokku source for larger, more in-depth examples.
### `install`
- Description: Used to setup any files/configuration for a plugin.
- Description: Can be used to run plugin updates on a regular interval. You can schedule the invoker in a cron-task to ensure your system gets regular updates.
- Invoked by: `dokku plugins-update`.
- Arguments: None
- Example:
```shell
#!/usr/bin/env bash
# Update the buildstep image from git source
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
cd /root/dokku
sudo BUILD_STACK=true make install
```
### `commands help`
- Description: Used to aggregate all plugin `help` output. Your plugin should implement a `help` command in your `commands` file to take advantage of this pluginhook. This must be implemented inside the `commands` pluginhook file.
- Invoked by: `dokku help`
- Arguments: None
- Example:
```shell
#!/usr/bin/env bash
# Outputs help for the derp plugin
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
case "$1" in
help | derp:help)
cat && cat<<EOF
derp:herp Herps the derp
derp:serp [file] Shows the file's serp
EOF
;;
*)
exit $DOKKU_NOT_IMPLEMENTED_EXIT
;;
esac
```
### `backup-export`
- Description: Used to backup files for a given plugin. If your plugin writes files to disk, this pluginhook should be used to echo out their full paths. Any files listed will be copied by the backup plugin to the backup tar.gz.
- Invoked by: `dokku backup:export`
- Arguments: `$VERSION $DOKKU_ROOT`
- Example:
```shell
#!/usr/bin/env bash
# Echos out the location of every `REDIRECT` file
# that are used by the apps
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
shopt -s nullglob
VERSION="$1"
DOKKU_ROOT="$2"
cat; for i in $DOKKU_ROOT/*/REDIRECT; do echo $i; done
```
### `backup-check`
- Description: Checks that a backup being imported passes sanity checks.
- Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to applications using buildstep.
- Invoked by: `dokku build`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `post-build-buildstep`
- Description: Allows you to run commands after the build image is create for a given app. Only applies to applications using buildstep.
- Invoked by: `dokku build`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `pre-build-dockerfile`
- Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to applications using a dockerfile.
- Invoked by: `dokku build`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `post-build-dockerfile`
- Description: Allows you to run commands after the build image is create for a given app. Only applies to applications using a dockerfile.
- Invoked by: `dokku build`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `pre-release-buildstep`
- Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to applications using buildstep.
- Invoked by: `dokku release`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
# Installs the graphicsmagick package into the container
ID=$(docker run -i -a stdin $IMAGE /bin/bash -c "$CMD")
test $(docker wait $ID) -eq 0
docker commit $ID $IMAGE > /dev/null
```
### `post-release-buildstep`
- Description: Allows you to run commands after environment variables are set for the release step of the deploy. Only applies to applications using buildstep.
- Invoked by: `dokku release`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
# Installs a package specified by the `CONTAINER_PACKAGE` env var
ID=$(docker run -i -a stdin $IMAGE /bin/bash -c "$CMD")
test $(docker wait $ID) -eq 0
docker commit $ID $IMAGE > /dev/null
```
### `pre-release-dockerfile`
- Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to applications using a dockerfile.
- Invoked by: `dokku release`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `post-release-dockerfile`
- Description: Allows you to run commands after environment variables are set for the release step of the deploy. Only applies to applications using a dockerfile.
- Invoked by: `dokku release`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `check-deploy`
- Description: Allows you to run checks on a deploy before dokku allows the container to handle requests.
