Building and Deploying Plugins

Build

[!note] This guide assumes you want to build a plugin for Notifly v2.0.0. If you want to build for a different version, replace v2.0.0 with the desired version.

Makefile notifly/plugin-template already contains tasks for most of the things you need to do when building a plugin; you can copy the Makefile into your own plugin project.

cd into the plugin source directory:

$ cd /path/to/plugin/source
$ ls
main.go go.mod go.sum

(Optional) Make sure there are no conflicting dependencies:

Get the go.mod file from Notifly. github.com/Notifly/blob/v2.0.0/go.mod and run the following commands:

$ go get -u github.com/notifly/plugin-api/cmd/gomod-cap
$ go run github.com/notifly/plugin-api/cmd/gomod-cap \
         -from /path/to/Notifly/source/go.mod -to /path/to/plugin/source/go.mod
$ go mod tidy

With Docker (recommended)

notifly/build Docker images are used to build Notifly. It is recommended to use the same build environment for plugins to ensure compatibility.

If you do not want to use the Makefile notifly/plugin-template you can build the plugin as follows:

Get the version of Go that was used to build Notifly. The version can be found in the Notifly repository in a file named GO_VERSION. github.com/Notifly/blob/v2.0.0/GO_VERSION. In this case it is 1.12.0.

Run the docker images. The tags for the notifly/build docker images have the following format: notifly/build:{GO_VERSION}-{GOOS}-{GOARCH}[-{GOARM}]. ([] means optional)

linux amd64

$ docker run --rm -v "$PWD/.:/proj" -w /proj notifly/build:1.12.0-linux-amd64 \
   go build -a -installsuffix cgo -ldflags "-w -s" -buildmode=plugin -o yourplugin-amd64.so /proj

linux arm-7

$ docker run --rm -v "$PWD/.:/proj" -w /proj notifly/build:1.12.0-linux-arm-7 \
   go build -a -installsuffix cgo -ldflags "-w -s" -buildmode=plugin -o yourplugin-arm-7.so /proj

linux arm64

$ docker run --rm -v "$PWD/.:/proj" -w /proj notifly/build:1.12.0-linux-arm64 \
   go build -a -installsuffix cgo -ldflags "-w -s" -buildmode=plugin -o yourplugin-arm64.so /proj

linux 386

$ docker run --rm -v "$PWD/.:/proj" -w /proj notifly/build:1.12.0-linux-386 \
   go build -a -installsuffix cgo -ldflags "-w -s" -buildmode=plugin -o yourplugin-386.so /proj

Without Docker (not recommended)

[!note] Plugins built without the Notifly build environment will likely not work with binaries from the Notifly releases.

Install the version of Go that was used to build Notifly. The version can be found in the Notifly repository in a file named GO_VERSION. github.com/Notifly/blob/v2.0.0/GO_VERSION.

If you are in GOPATH, explicitly enable go modules:

$ export GO111MODULE=on

Build the plugin:

$ go build -o /path/to/notifly/plugin/dir/myplugin.so -buildmode=plugin

Deployment

Notifly loads plugins from the pluginsdir directory in the configuration. All files in that directory are loaded as plugins.

Copy the built shared object into the notifly plugins directory:

$ cp myplugin.so "${NOTIFLY_PLUGINSDIR}/myplugin.so"

Run notifly:

$ notifly

Troubleshooting

cannot load plugin (<plugin_filename>): package (<plugin_package>) was built with another version of package(<conflicting_package>)

• If the conflicting package is from the standard library (does not start with a host name):
  • Check whether the plugin was built with go modules enabled (try GO111MODULE=on)
  • If you are using an official release, the plugin must be built with the same version of the go toolchain as the build environment (go version)
• If the conflicting package is a third-party dependency (starts with a host name, e.g.: github.com/...):
  • Check whether your project file go.mod is up to date (go mod tidy)
  • The plugin may share a dependency with notifly but with a different version; change the dependency version manually in go.mod or use gomod-cap.
• If you still cannot resolve dependency issues, try to build notifly from source.