Adjust plugin development instructions to graylog-project-cli

[bernd]

Our current plugin development instructions still use some scripts which have been removed from the graylog-project repository. We should update the instructions to use graylog-project-cli.

[danotorrey]

I am planning to do this at the same time as I update the plugin creation instructions.

[jrunu]

Is the functionality there, just not documented yet or would it be prefereable to use the pre-graylog-project-cli way for now? Considering writing a plugin for Graylog 3.x. Thanks!

[danotorrey]

Hi @jrunu, You can use our Graylog Plugin Maven archetype to create a plugin:

mvn archetype:generate -DarchetypeGroupId=org.graylog -DarchetypeArtifactId=graylog-plugin-archetype.

Once run, it will create a Graylog plugin sources. You can open the new plugin in your IDE to begin working with code. If you are targeting a particular Graylog version, you can update the parent.version in the pom.xml file accordingly.

The most effective way to develop plugins for Graylog is to set up a full Graylog development environment:

1. Install the latest Graylog CLI binary on your machine. Make sure it's on your PATH.

2. Create a git repository and push your new plugin project/files to it.

3. Set up a Graylog development environment on your computer. Follow the instructions on the README here. This will create a graylog-project and graylog-project-repos directory.

4. In the graylog-project/manifests folder, create an XML manifest that looks like this (except with your git repository and plugin name)

  "includes": [ "master.json" ],
  "modules": [
    {
      "repository": "[email protected]:danotorrey/test-graylog-plugin.git",
      "revision": "master",
      "assemblies": ["your-new-plugin"]
    }
  ]
}

5. Go to the graylog-project folder and run graylog-project checkout -u manifest/path-to-your-manifest.xml. This will check out your new plugin from git and integrate it into the Graylog development environment.

6. Open the graylog-project folder into your IDE, and all Graylog sources and your new plugin should be automatically detected/imported.

[jrunu]

Thank you @danotorrey for the step by step guide!

When doing the mvn compile with my own manifest it prompted me with this error:

Failure to find org.graylog.plugins:graylog-plugin-web-parent:pom:3.0.0-alpha.3-SNAPSHOT in https://oss.sonatype.org/content/repositories/snapshots was cached in the local repository, resolution will not be reattempted until the update interval of sonatype-nexus-snapshots has elapsed or updates are forced and 'parent.relativePath' points at wrong local POM @ line 6, column 13

Changing the version of it to 3.1.0-SNAPSHOT resolved that. After removing the (unused) import sun.security.provider.SHA from graylog2-server/src/main/java/org/graylog2/rest/models/system/indexer/responses/ShardRouting.java everything but the plugin skeleton I created built well. It can't find the the org.graylog2.plugin package. I'm still investigating that one.

[danotorrey]

@jrunu Certainly! Thanks for working on this so soon.

Thanks for the note on the incorrect version in the mvn archetype. We'll fix that.

Which class is displaying the org.graylog2.plugin package resolution error?

[jrunu]

Which class is displaying the org.graylog2.plugin package resolution error?

In all three *Plugin, *Module and *MetaData java files. The precise error message is "package org.graylog2.plugin does not exist".

[danotorrey]

@jrunu This is is most likely due to an issue with the parent pom file, which is how the all of the Graylog core dependencies are imported.

The best way to make sure the parent pom dependencies are imported, is to ensure that the plugin is being developed in a full Graylog development environment (as described in this comment above). Have you performed this setup yet?

[jrunu]

@danotorrey it works now. My guess is that I messed something up on the first try. There was something odd with the artifactsID. I regenerated the plugin skeleton then redid all the steps and threw away the IDEA project. I now have (a sample) plugin jar that loads into my test setup just fine. Thanks for your help.

[danotorrey]

@jrunu That is fantastic news. Thank you for the update! Let us know if any other questions arise as you work on the plugin.

[danotorrey]

@bernd I will rework the plugin docs to reference the new CLI instructions as I outlined above. We can refine the working and steps once I draft a PR.