My First Maven Plugin

arrow_backback
- 03 Jul 2021

I made a maven plugin that loads the key/value pairs in .env files into the jvm environment variables during the maven build phases. Click here to go to the plugin’s github.

Last year, I started working at Athena Software (now acquired by Social Solutions Global) as a full stack web developer. We use Java for the backend of our main product, and as such maven is our build tool.

Over the course of the year, I’d occasionally run into some quirk or problem that would prompt me to get a better understanding as to how maven worked. This all culminated in trying to make my first maven plugin: env-file-maven-plugin

What does it do?

The plugin looks for a dotenv (.env) file and loads its key/value pairs into environment variables during different phases of the maven build process.

I needed this because I wanted to follow 12-factor app principles with a new personal project I was building, and I realized that all the suggestions I was reading for loading environment variables during the maven build phase didn’t include reading from a file that I could easily .gitignore. Specifically, I needed environment variable values for the tests executed during the test phase, which is executed when your run mvn package.

Yes, I could have made a copy of the pom.xml file, such as pom.xml.dist and then .gitignored that, but that looked really funky and wasn’t something I had seen in any other java project. Rather than recognize it as a sign that I was doing something funky, I tried to bruteforce my way to do things wrong, and hopefully learn something along the way.

I do believe I have succeeded on both accounts

Lessons learned

I won’t include yet another tutorial on how I made the plugin, it’s documentation, and publishing it to the central maven repository as I believe that space has been covered already in extreme detail. I will however talk about the general experience itself of making the plugin.

Plugin Implementation

While actually implementing the desired functionality was extremely easy and completed from scratch after a couple hours of fiddling, the documentation and publishing side were a lot more finicky.

Documentation

Maven plugins can have their own site documentation generated by the maven-site-plugin. You list out the “reports” you want to generate, which “skin” you want your documentation to use and what kind of markup language that your site pages will be written in. You can then generate your site’s documentation with mvn site, which can even be hooked up to github with github pages to then immediately publish the site as a static webpage.

It’s all very cool and the payoff would have been worth the effort if I had published a plugin that I’d expect someone else to actually use.

Publishing

Publishing was more involved than I expected. The main differences between publishing to maven central vs something like the npm registry was that I had to

  1. have hosted documentation on a website
  2. verify that I owned the website
  3. sign all the jar files with my own published gpg key

While #3 is definitely something I’d expect when you’re effectively uploading compiled executables (the jar files), #s 1 and 2 were nice to see as they were small steps that tried to enforce some sort of quality control.

The main pain-point here was getting the plugins configured in the pom file in the right places and actually executing when they should. I’m not 100% if it was actually required, but I ended up having to run the release command with a profile in order to force signing.

The command was mvn prepare:release -P release-sign-artifacts

Final Remarks

You can expect that all the articles you find will be out-dated in some form or another. You’ll have to spend some time verifying the pom.xml config that you were given is both still valid and up-to-date (it won’t be).

However, you can rest assured that you’re being pointed in the right direction as Apache Maven has an invested interest in ensuring that you’re able to effectively write, document and publish new maven plugins.

References

Implementation:

(really, that’s all that was needed. Fantastic documentation)

Documentation

Publishing