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

Edits for readability and conciseness

Browse Source
This commit is contained in:
V Anastassiou
2019-04-17 14:03:48 -07:00
committed by GitHub
parent e5c76d3795
commit c4c7d0d82d
1 changed files with 41 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/development/plugin-creation.md
View File

@@ -1,37 +1,37 @@
# Plugin Creation
# Plugin creation
Plugins can simply be implementations of [triggers](/docs/development/plugin-triggers.md) or they may implement a command structure of their own. Dokku has no restrictions on the language in which a plugin is implemented, it only cares that the plugin implements the appropriate [commands](/docs/development/plugin-creation.md#command-api) or [triggers](/docs/development/plugin-triggers.md) API. NOTE: all files that implement the triggers or commands API must be executable.
A plugin can be a simple implementation of [triggers](/docs/development/plugin-triggers.md) 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](/docs/development/plugin-creation.md#command-api) or [triggers](/docs/development/plugin-triggers.md) 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](/docs/development/plugin-triggers.md) 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](/docs/community/plugins.md) and add a link to it.
1. Take a look at [the plugins shipped with Dokku](https://github.com/dokku/dokku/blob/master/docs/community/plugins.md) and hack away!
2. Check out the [list of triggers](/docs/development/plugin-triggers.md) 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](/docs/community/plugins.md) and add a link to your plugin
5. Subscribe to the [dokku development blog](http://progrium.com) to be notified about API changes and releases
### Compilable Plugins (i.e. golang, java(?), c, etc.)
The plugin developer is required to implement the `install` trigger such that it will output your built executable(s) in the correct directory structure to implement the plugin's desired command and/or trigger API. See [smoke-test-plugin](https://github.com/dokku/smoke-test-plugin) for an example.
## 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](https://github.com/dokku/smoke-test-plugin) for an example.
### Command API
There are 3 main implementation points: `commands`, `subcommands/default`, and `subcommands/<command-name>`
## 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](https://github.com/dokku/dokku/tree/master/plugins/plugin/commands))
### `commands`
Primarily used to supply the plugin's usage/help output. (i.e. [plugin help](https://github.com/dokku/dokku/tree/master/plugins/plugin/commands)).
#### subcommands/default
Implements the plugin's default command behavior. (i.e. [`dokku plugin`](https://github.com/dokku/dokku/tree/master/plugins/plugin/subcommands/default))
### `subcommands/default`
Implements the plugin's default command behavior. (i.e. [`dokku plugin`](https://github.com/dokku/dokku/tree/master/plugins/plugin/subcommands/default)).
#### subcommands/<command-name>
Implements the additional command interface and will translate to `dokku plugin:cmd` on the command line. (i.e. [`dokku plugin:install`](https://github.com/dokku/dokku/tree/master/plugins/plugin/subcommands/install))
### `subcommands/<command-name>`
Implements the additional command interface and will translate to `dokku plugin:cmd` on the command line. (i.e. [`dokku plugin:install`](https://github.com/dokku/dokku/tree/master/plugins/plugin/subcommands/install)).
### Sample plugin
# Sample plugin
The below plugin is a dummy `dokku hello` plugin.
hello/subcommands/default
`hello/subcommands/default`
```shell
#!/usr/bin/env bash
@@ -59,7 +59,7 @@ hello_main_cmd() {
hello_main_cmd "$@"
```
hello/subcommands/world
`hello/subcommands/world`
```shell
#!/usr/bin/env bash
@@ -87,7 +87,7 @@ hello_world_cmd() {
hello_world_cmd "$@"
```
hello/commands
`hello/commands`
```shell
#!/usr/bin/env bash
@@ -136,15 +136,15 @@ version = "0.1.0"
[plugin.config]
```
A few notes:
# A few notes:
- Don't forget to `chmod +x` your executable files.
- 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. Also, the command syntax will need to separated by `, ` in order to maintain columnar output alignment.
- 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.
- Be sure you want the "set -eo pipefail" option. Look at the following example :
- 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 :
```shell
IMAGE=$(docker images | grep "user/repo" | awk '{print $3}')
@@ -153,10 +153,9 @@ A few notes:
fi
```
In the case where the "user/repo" is not installed, Dokku exits just before the awk command,
you will never see the message printed with echo. You just want "set -e" in this case.
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 documentation of the 'set -eo pipefail' option:
Here is the `help` entry for `set`:
```
help set
Options:
@@ -166,13 +165,19 @@ A few notes:
the last command to exit with a non-zero status,
or zero if no command exited with a non-zero status
```
- As some plugins require access to set app config settings and do not want/require the default Heroku-style behavior of a restart, we have the following "internal" commands that provide this functionality :
- 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:
```shell
dokku config:set --no-restart node-js-app KEY1=VALUE1 [KEY2=VALUE2 ...]
dokku config:unset --no-restart node-js-app KEY1 [KEY2 ...]
```
- From time to time you may 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. Consider all functions in that file to be publicly accessible by other plugins. Any functions not wished to be made "public" should reside within your plugin trigger or commands files.
- As of 0.4.0, we allow image tagging and deployment of said tagged images. Therefore, hard-coding of `$IMAGE` as `dokku/$APP` is no longer sufficient. Instead, for non `pre/post-build-*` plugins, use `get_running_image_tag()` & `get_app_image_name()` as sourced from common/functions. See the [plugin triggers](/docs/development/plugin-triggers.md) doc for examples.
- As of 0.5.0, we use container labels to help cleanup intermediate containers with `dokku cleanup`. If manually calling `docker run`, include `$DOKKU_GLOBAL_RUN_ARGS`. This will ensure you intermediate containers labeled correctly.
- As of 0.6.0, we advise you to *not* call the `dokku` binary directly from within plugins. Clients using the `--app` argument are potentially broken, amongst other issues, when doing so. Instead, please source the `functions` file for a given plugin when attempting to call Dokku internal functions
- 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](/docs/development/plugin-triggers.md) 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