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!
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.
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.
How to do it
To add a plugin you need to SSH into the server
Edit the main
containers/app.ymlconfig 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.
-(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+Oto save then
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.ymlto 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
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
admin/pluginsroute on your Discourse instance.
If all is well you can close the SSH session (type
“What about the data/database tables created by the plugin? What happens to those?”
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.
- We are writing another guide all about Discourse Development - I’d suggest you go and have a look there: https://thepavilion.io/t/the-discourse-developer-guide