Mirrors/dokku
1
0
Fork 0
mirror of https://github.com/dokku/dokku.git synced 2026-02-23 19:50:34 +01:00
Code Issues Packages Projects Releases Wiki Activity

[ci skip] update docs

Browse Source
This commit is contained in:
Michael Hobbs
2015-06-16 10:02:38 -07:00
committed by Jose Diaz-Gonzalez
parent 6d70751cfc
commit 2a4cbc7bee
4 changed files with 38 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/development/plugin-creation.md → docs/development/plugn-creation.md
View File

@@ -1,14 +1,14 @@
# Plugin Creation
# Plugn Creation
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 hooks](http://progrium.viewdocs.io/dokku/development/pluginhooks) your plugin can implement.
2. Check out the [list of hooks](http://progrium.viewdocs.io/dokku/development/plugn-triggers) your plugin can implement.
3. Upload your plugin to github with a repository name in form of `dokku-<name>` (e.g. `dokku-mariadb`)
4. Edit [this page](http://progrium.viewdocs.io/dokku/plugins) and add a link to it.
5. Subscribe to the [dokku development blog](http://progrium.com) to be notified about API changes and releases
### Sample plugin
### Sample plugn
The below plugin is a dummy `dokku hello` plugin. If your plugin exposes commands, this is a good template for your `commands` file:
@@ -31,7 +31,7 @@ case "$1" in
;;
help)
cat && cat<<EOF
cat<<EOF
hello <app>, Says "Hello <app>"
hello:world, Says "Hello world"
EOF
@@ -44,6 +44,15 @@ EOF
esac
```
Each plugn requires a `plugin.toml` descriptor file with the following required fields:
```shell
[plugin]
description = "dokku hello plugin"
version = "0.1.0"
[plugin.config]
```
A few notes:
- You should always support `DOKKU_TRACE` as specified on the 2nd line of the plugin.

40
docs/development/pluginhooks.md → docs/development/plugn-triggers.md
View File

@@ -1,15 +1,15 @@
# Pluginhooks
# Plugn triggers
[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.
[Plugn triggers](https://github.com/progrium/plugn) 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:
Plugn triggers 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.
For instance, if you wanted to write a plugn trigger in PHP, you would need to have `php` installed and available on the CLI prior to plugn trigger 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:
The following is an example for the `nginx-hostname` plugn trigger. 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 plugn trigger, it would be invoked by dokku during the normal app deployment process:
```shell
#!/usr/bin/env bash
@@ -21,17 +21,17 @@ NEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`
echo "$NEW_SUBDOMAIN.$VHOST"
```
## Available Pluginhooks
## Available Plugn triggers
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.
There are a number of plugin-related triggers. These can be optionally implemented by plugins and allow integration into the standard dokku 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 following plugn triggers describe those available to a dokku installation. As well, there is an example for each trigger that you can use as templates for your own plugn 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.
> The example plugn trigger 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: Used to setup any files/configuration for a plugn.
- Invoked by: `dokku plugins-install`.
- Arguments: None
- Example:
@@ -57,7 +57,7 @@ fi
```shell
#!/usr/bin/env bash
# Installs nginx for the current plugin
# Installs nginx for the current plugn
# Supports both opensuse and ubuntu
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
@@ -76,7 +76,7 @@ esac
### `update`
- 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.
- Description: Can be used to run plugn 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:
@@ -93,20 +93,20 @@ 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.
- Description: Used to aggregate all plugn `help` output. Your plugn should implement a `help` command in your `commands` file to take advantage of this plugn trigger. This must be implemented inside the `commands` plugn file.
- Invoked by: `dokku help`
- Arguments: None
- Example:
```shell
#!/usr/bin/env bash
# Outputs help for the derp plugin
# Outputs help for the derp plugn
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
case "$1" in
help | derp:help)
cat && cat<<EOF
cat<<EOF
derp:herp, Herps the derp
derp:serp [file], Shows the file's serp
EOF
@@ -121,7 +121,7 @@ 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.
- Description: Used to backup files for a given plugn. If your plugn writes files to disk, this plugn trigger should be used to echo out their full paths. Any files listed will be copied by the backup plugn to the backup tar.gz.
- Invoked by: `dokku backup:export`
- Arguments: `$VERSION $DOKKU_ROOT`
- Example:
@@ -157,7 +157,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
### `backup-import`
- Description: Allows a plugin to import specific files from a `$BACKUP_ROOT` to the `DOKKU_ROOT` directory.
- Description: Allows a plugn to import specific files from a `$BACKUP_ROOT` to the `DOKKU_ROOT` directory.
- Invoked by: `dokku backup:import`
- Arguments: `$VERSION $BACKUP_ROOT $DOKKU_ROOT $BACKUP_TMP_DIR/.dokku_backup_apps`
- Example:
@@ -513,8 +513,8 @@ echo false
```shell
#!/usr/bin/env bash
# Reloads haproxy for our imaginary haproxy plugin
# that replaces the nginx-vhosts plugin
# Reloads haproxy for our imaginary haproxy plugn
# that replaces the nginx-vhosts plugn
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
@@ -596,7 +596,7 @@ nginx -t
```shell
#!/usr/bin/env bash
# For our imaginary mercurial plugin, triggers a rebuild
# For our imaginary mercurial plugn, triggers a rebuild
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x

5
docs/plugins.md
View File

@@ -1,10 +1,11 @@
# Plugins
Dokku itself is built out of plugins and uses [pluginhook](https://github.com/progrium/pluginhook) for its plugin system. In essence a plugin is a collection of scripts that will be run based on naming convention.
Dokku itself is built out of plugins and uses [plugn](https://github.com/progrium/plugn) 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/
├── plugin.toml # plugin metadata
├── commands # contains additional commands
├── install # runs on dokku installation
└── post-deploy # runs after an app is deployed
@@ -12,7 +13,7 @@ Let's take a quick look at the current dokku nginx plugin that's shipped with do
## Installing a plugin
```shell
cd /var/lib/dokku/plugins
cd /var/lib/dokku/plugins/available
git clone <git url>
dokku plugins-install
```

4
docs/template.html
View File

@@ -76,8 +76,8 @@
<a href="#" class="list-group-item disabled">Development</a>
<a href="http://progrium.viewdocs.io/dokku/development/plugin-creation" class="list-group-item">Plugin Creation</a>
<a href="http://progrium.viewdocs.io/dokku/development/pluginhooks" class="list-group-item">Pluginhooks</a>
<a href="http://progrium.viewdocs.io/dokku/development/plugn-creation" class="list-group-item">Plugn Creation</a>
<a href="http://progrium.viewdocs.io/dokku/development/plugn-triggers" class="list-group-item">Plugn Triggers</a>
<a href="http://progrium.viewdocs.io/dokku/development/testing" class="list-group-item">Test Suite</a>
<a href="http://progrium.viewdocs.io/dokku/development/release-process" class="list-group-item">Release Process</a>
</div>