Creating your own QGIS plugin store

On the long road to open source GIS we’ve been looking at how best to deploy QGIS plugins to our clients.

In the spirit of free software we’re really keen on getting our tools into the official QGIS plugin store but until we’re confident our plugins are usable by the general public it’s nice to have a way to deploy plugins amongst ourselves.

I’m not advocating this for general plugins that would be useful for other . people. QGIS is an open source movement and if you’ve got a great plugin that makes toast better than anyone else you should definitely jump through the hoops to get it on the official store so others can find it.

Some cases where having your own store might be nice include proof-of-concepts, experiments and plugins that are so specific to your project/organization that others wouldn’t find them useful.

There’s nothing stopping you from just emailing your plugins as a zip file that people drop into the ~/.qgis2/python/plugins folder but I like having an automatic upgrade path, even for developer versions. This way I can message someone telling them to simply click an update button and not have to worry that they didn’t replace the plugins folder correctly.

Luckily for us it ended up being trivial to get our own custom store written and up online using GitHub Pages. The benefits of doing it thus way are:

1. Our store is version-controlled our store in git.
2. Free web hosting!
3. Taking advantage of Jekyll theming

Ok, let’s get started.

Creating the Store

QGIS shows its store to be simply a url: https://plugins.qgis.org/plugins/plugins.xml

If you view the source for this you can see that it’s just a really basic XML file with a <plugins> tag wrapping around a bunch of <pyqgis_plugin> definitions.

Documentation was a little hard to find for what tags are actually used but if we follow the same pattern we should end up with something usable and create our own that looked something like this:

I tossed my xml file up onto a web server and fed the url to QGIS as a new store. Sure enough, it showed up in my list of stores. Furthermore it told me my new plugin was ready to download!

Deploying your plugins

Now that I had a store in place the rest is relatively straightforard. Plugins are just hosted zip files so upload them somewhere public and link to them from your store xml. We use S3 to host files so I wrote a little shell script that uses pb_tool to compile and deploy a new version to keep things consistent.

Pass in the version number as an argument

Styling your homepage:

Now that you’re a QGIS store expert you might be looking at your XML file in a browser and noticing that it’s not very pretty or responsive.

https://plugins.qgis.org/plugins/plugins.xml functional but not very pretty or responsive.

Wouldn’t it be nice for it to match our website theme and also include some instructions of how to use it? If people don’t want to use the in-built QGIS store they can still download zip files from the webpage so making it look nice is worth a little effort.

If you look at the source code you’ll notice <?xml-stylesheet> tag. In the past we’ve used XSL transforms to create attractive reports from XML files so it didn’t take much of a leap to create a style for this simple XML file:

We use Foundation for our responsive theming framework so the class tags you see correspond to pre-made CSS for rows, columns, labels, buttons etc.

I called this file plugins.xsl and dropped it into the root of my Jekyll site next to my store file plugins.xml. The Jekyll FrontMatter at the top of the file is used to fold this into the templating system and when the Jekyll site deploys we end up with something that matches the rest of our site’s theme.

Our pretty, responsive new store with two of our new plugins ready for install.

Gotchas

There was one problem that took me forever to figure out. There are apparently some rules on how the zipfiles are named. MyPlugin.0.3.3.zip is apparently ok but MyPlugin-0.3.3.zip is not. The symptom is that the zip file will download and install the plugin but QGIS will immediately reject it and require a restart before the new plugin shows up.

To get around this we removed versions from filenames entirely and opted to use versioned folders instead:

/plugins/networkprofiler/v0.6/NetworkProfiler.zip

I’m happy for someone to tell me this is not the proper way to do things but it’s working for now so I’m going with it.