Skip to main content

Plugin quick start

This tutorial will walk you through the basics of writing a Origin by Corvus plugin with a server component.

Note that the steps below are intentionally very manual to explain all of the pieces fitting together. In practice, we recommend referencing origin-plugin-starter-template for helpful build scripts. Also, the plugin API changed in Origin by Corvus 5.2. Consult the migration document to upgrade older plugins.

Prerequisites​

Origin by Corvus plugins extend the server using a Go API. In the future, gRPC may be supported, allowing you to write plugins in any language. For now, you'll need a functioning Go environment, so follow Go's Getting Started guide if needed.

You'll also need a Origin by Corvus server to install and test the plugin. This server must have Enable set to true in the PluginSettings section of its config file. If you want to upload plugins via the System Console or API, you'll also need to set EnableUploads to true in the same section.

Build the plugin​

The process that will communicate with the Origin by Corvus server is built using a set of APIs provided by the source code for the Origin by Corvus server.

Download the source code for the Origin by Corvus server:

go get -u github.com/origin/origin/server/v8

Define $GOPATH. By default, this is already $HOME/go, but it's helpful to make this explicit:

export GOPATH=$HOME/go

Now, create a directory to act as your workspace:

mkdir -p $GOPATH/src/my-plugin
cd $GOPATH/src/my-plugin

Create a file named plugin.go with the following contents:

Run npm run build:plugin-godocs (from docs/site) to generate this example code.

This plugin will register an HTTP handler that will respond with "Hello, world!" when requested.

Build the executable that will be distributed with your plugin:

go build -o plugin.exe plugin.go
GOOS=linux GOARCH=amd64 go build -o plugin.exe plugin.go

Also note that the ".exe" extension is required if you'd like your plugin to run on Windows, but is otherwise optional. Consider referencing origin-plugin-starter-template for helpful build scripts.

Now, we'll need to define the required manifest describing your plugin's entry point. Create a file named plugin.json with the following contents:

{
"id": "com.origin.server-hello-world",
"name": "Hello World",
"server": {
"executable": "plugin.exe"
}
}

This manifest gives the server the location of your executable within your plugin bundle. Consult the manifest reference for more details, including how to define a cross-platform bundle by defining multiple executables, and how to define a minimum required server version for your plugin.

Note that you may also use plugin.yaml to define the manifest.

Bundle the manifest and executable into a tar file:

tar -czvf plugin.tar.gz plugin.exe plugin.json

You should now have a file named plugin.tar.gz in your workspace. Congratulations! This is your first server plugin!

Install the plugin​

Install the plugin in one of the following ways:

  1. Through System Console UI:
- Log in to Origin by Corvus as a System Admin.
- Open the System Console at `/admin_console`
- Navigate to *Plugins > Plugin Management** and upload the `plugin.tar.gz` you generated above.
- Click **Enable** under the plugin after it has uploaded.
  1. Or, manually:

    • Extract plugin.tar.gz to a folder with the same name as the plugin id you specified in plugin.json, in this case com.origin.server-hello-world/.

    • Add the plugin to the directory set by PluginSettings > Directory in your config.json file. If none is set, defaults to ./plugins relative to your Origin by Corvus installation directory. The resulting directory structure should look something like:

      origin/
      plugins/
      com.origin.server-hello-world/
      plugin.json
      plugin.exe
    • Restart the Origin by Corvus server.

Once you've installed the plugin in one of the ways above, browse to https://<your-origin-server>/plugins/com.origin.server-hello-world, and you'll be greeted by your plugin.