Plugins

Education Discourse Sysadmin Guide
1

As a Discourse sysadmin you’re probably going to want to add at least one plugin. Possibly many more than one - they can add great new functionality to your Discourse site and this can be great for your community!

Discovering Plugins

  • In the main you will find plugins on Discourse Meta. While this is great, everything’s in one place, you can browse and search, but it can be difficult to find ‘the plugin you never thought you needed’. To help with this, we’re working on curated lists of Discourse plugin recommendations for certain types of community.

  • The Plugin Directory lists the plugins available on the different tiers of Discourse.org’s services. Don’t worry about the pricing tiers - that’s just their internal pricing system for the service - all those plugins are available free and open source for you to use!

  • ‘Official’ Discourse plugins are the ones produced by the Discourse team and they are generally recognised as being reliable and well maintained. They’re less likely to break when there is a Discourse update, because (presumably) the Discourse team checks plugins when update code is being tested.

Plugin safety and reliability

  • Plugins extend the feature set of Discourse and they can access and control any aspect of your Discourse forum. They install Ruby code on the server side and JavaScript/HTML/CSS on the client.

  • Don’t install plugins from non-trusted sources, as potentially any aspect of the forum’s database is accessible to the plugin. We’re not aware of any examples of malicious plugins in the Discourse ecosystem (yet?) - and the fact that plugins are mainly installed from open source Git repositories makes them easier to scrutinise. But still. Be safe.

  • Plugins can break. For example, if something significant changes within Discourse’s codebase that the plugin was relying on, then the plugin may not work, malfunction, or just crash. So beware of adding a lot of plugins since you can sometimes be creating problems for yourself down the line. These problems tend to occur when you update your site, so beware of updating the site unless you know that the plugin is going to be OK.

  • Consider the use of a separate ‘testing’ or ‘staging’ server so that you can check that new updates to Discourse don’t break your plugins, especially if you have a complex setup.

  • Here at The Pavilion, with our own plugins, we recommend to update your site on the first few days of the month so that we are available to fix any issues that arise with new Discourse updates or features. We also offer a Managed Updates service that lets us take care of your updates for you.

Installing a plugin from a simple Git repository

How to do it

To add a plugin you need to SSH into the server

cd to /var/discourse

Edit the main containers/app.yml config file as root - the simplest way is to use sudo nano containers/app.yml

scrolling right to the bottom you will find a section that looks like this:

## Plugins go here
## see https://meta.discourse.org/t/19157 for details
hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone https://github.com/discourse/docker_manager.git

add the Git repository URL for your plugin after the line that says - git clone ...

IMPORTANT: the config file uses YAML which is very sensitive to correct indentation.

Before the - (dash) character there must be EXACTLY TEN SPACES of indentation. More or less and either the server container will not rebuild, or the plugin just won’t be added. It must be SPACES not tabs.

After you’re done it should look like:

## Plugins go here
## see https://meta.discourse.org/t/19157 for details
hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone https://github.com/discourse/docker_manager.git
          - git clone https://github.com/organisation/plugin-name.git

Save and exit nano with Ctrl+O to save then Ctrl+X to leave.

Rebuild the container to pull in the new changes and rebuild the container.

./launcher rebuild app

It’ll take about 5 minutes to do the rebuild and it will tell you at the end that it’s been successful with a block of config values and settings. If it failed it will clearly say ‘FAILED’.

Tip: If the container fails after a new plugin addition, it’s is almost always because of incorrect indentation in the app.yml. You can use online services like YAMLLint to check the validity of your app.yml. (I recommend you use cat containers/app.yml to spool the contents of the file to the terminal so you can copy and paste it into the YAML linter - don’t try to do it in nano!)

Go back to the webapp and refresh the page to get the updated version. You should be able to view the new Plugin you added by going to the https://discourse.mydomain.com/admin/plugins route on your Discourse instance.

If all is well you can close the SSH session (type exit)

Installing a plugin from a private repository

TODO

Installing a plugin from a non-default Git branch

TODO

Removing a plugin

TODO
“What about the data/database tables created by the plugin? What happens to those?”

Contributing to and improving plugins

  • Plugins are developed by Discourse themselves (CDCK) on open source license terms, because they (and we!) believe strongly in open source software.

  • Many other developers also develop plugins for Discourse. Some develop in open source, some in closed source. Unless you have paid for your own plugins to be developed then you are almost certainly going to be using the open source plugins

  • Most plugin developers are doing this for free or for very little. So if you have feedback for them, please remember to be nice! They are much more likely to add your feature or fix your bug if you’re nice.

  • You can report bugs with a plugin by going to that plugin’s main Topic on Discourse. Some developers will also be using something like GitHub Issues, which can be accessed at the Issues tab of the GitHub repository that the plugin was installed from.

  • If you really need a bugfix, feature, or improvement, and are willing to pay for it, then you might want to contact the developer using a private message on Meta to discuss this. Remember that this kind of work is highly specialised, highly skilled, and in-demand - so bear this in mind when thinking about your budget.

Developing plugins

1 Like