Purpose of this plugin
This plugin does two things:
Fundamentally, allows you to power a Discord bot using your Discourse server to do stuff to link the two systems.
Currently supports two commands which help sync membership of your Discord server with your Discourse instance.
these aren’t the two sync commands, just an illustration of bot interaction that is possible. the second command in the screenshot was deprecated during development
It is necessarily complex to set up, but great for fans of both systems who are keen to put the time in to understand how each system works, at least on a functional and conceptual level. You need to understand some of the fundamentals of how Discourse and Discord user management works to get the best out of this plugin.
State of this plugin
This is a complex plugin to set-up. That was pretty unavoidable.
However, it’s child’s-play to use once it’s all up and running.
Consider the code as currently in Beta. It’s been tested, even in Production, but likely to contain bugs. I recommend testing this first on a fresh Discord server before applying it to your “Production” main Discord server, unless you are just starting out.
Any bugs are much more likely to upset your Discord instance than your Discourse instance, because there are no changes made to Discourse. However, I’ve written it in a way that means most things are recoverable and you can merely repeat something to fix an issue usually. Discourse is used as a master for membership and group information and this data is used to update membership and Roles on your Discord server.
- a Discord server on which you are Admin
- a Discord App (see below)
- a Discord Bot (see below)
- ssh root access to your Discourse server
- updates to app.yml to
libsodium, a dependency (see below)
- install the two required plugins (this one you are reading about and the Discord OAuth login plugin) (again, see below)
- All users of your Discourse will need to login using Discord OAuth login that will appear on your login page once the plugin is installed.
Go here and create an app:
Hit “New Application”
You will need to create a Bot and it will look something like this (leave it not ‘public’):
You will need to authorise the bot in the browser, see Discord Developer Portal
Once the bot is set up, copy the Token. You will need to enter that into Discourse later.
You need two plugins for this. (The first is not originally mine but you need my forked changes presently until my PR is accepted and merged)
- GitHub - merefield/discourse-plugin-discord-auth: A Discourse plugin to login over Discord
- GitHub - merefield/discourse-discord-bot: A Discord bot that runs on your Discourse server to link the two servers.
This library is required for the
discordrb gem, installed by
plugin.rb, to work.
hooks: before_code: - exec: cmd: - apt-get update - apt-get install -y libsodium-dev
This goes just above where you specify your plugins. The
hooks statement should pre-exist. You need to add the plugins to the plugin section directly beneath this.
Then at the prompt
./launcher rebuild app as usual.
This should work, np.
You may get some console and log errors indicating a failure of the bot on first build as you’ve not yet entered the bot’s credentials in the front end of Discourse’s settings yet. (more gracefully handling this is a todo, I’ll delete this bit when that gets done). It will do no harm though and Discourse itself will work normally.
Once in your Discourse admin area, go to Plugin Settings and fill these:
You will get the IDs from Discord interface. You will need to activate Developer Mode to allow you to copy these IDs. In Discord, go to your Settings - > Appearance - > ADVANCED and enable Developer Mode:
You can then get ID’s on from the interface, e.g.:
You will also need to fill in the Discord OAuth Settings. The Client ID and Secret are from your very same Discord App.
Once you’ve set these, go back to your root prompt in linux and type:
./launcher restart app
If you’ve set up your Discord and Discourse servers correctly, you should see the bot join the server.
If ever the bot falls over (it will go offline) you will need to do the same thing again to bring it back. Improved independence of the bot from the Discourse core server is a to do. That said, I’ve run a bot in Production for a long while and it’s yet to fall over.
There are three commands:
To check if the bot is responding, just type “Ping!” and the bot should respond with “ : Pong!” - marvellous, eh? (this is a bit of a meme btw!)
!disckick <min_trust_level: default 2>
Typing this will kick any user that exists on your Discourse but at a Trust Level below your supplied value. The default if you don’t supply a value is 2.
!discsync <clean up: default false, min_visibility: default 0, include automated groups: default false>
This command will attempt to copy over all groups into Roles on Discord which match provided criteria (or defaults if not provided). It will then attempt to populate the roles as per the Group membership on Discourse. It’s a one way sync only. No Discourse data is ever changed.
If you have an idea for another command that leverages the link between Discourse and Discord that you believe would be useful to the wider community let me know in the replies and we can look at the potential to implement that. NB this bot is not intended to perform tasks outside the scope of Discourse.
The main goal of this plugin was to allow the user to create a bot on their Discord that would be powered by their Discourse server and be able to carry out some basic membership management functions. It also provides a foundation for any additional bot-like interactions between the two systems for the future. Part of the motivation for using bots is that they are just plain fun.
Apologies, only English language is presently supported and have yet to add hooks to support translation, partly because there’s quite a lot of language. Let me know if that’s a huge issue.
Bot commands are ad hoc by their very nature.
I have also been working on another plugin which avoids the use of bot commands and instead uses more vanilla REST calls from Discourse to manage things. The advantage of that approach is that you can create a batch process to sync things periodically without having to initiate the process every time. I’ll see if I have time to complete that given competing priorities …
The Robot is a bit chatty during ‘online’ Discourse upgrades as keeps getting reactivated during the upgrade process. This comes back to working out a good way to running the bot in a separate, managed process instead of a thread branched off the webserver. I believe this is all harmless though, and if the bots output is only to your admin channel on Discord, do you really care?
There are several backers to thank for this plugin which took me a big while to get to this stage inc. @Wedgebert, @FoohonPie. Thanks to Jeff for his generous contribution. Thanks to @angus for all the encouragement and dealing with the financial support.
The plugin relies on the semi-official Discord-backed
discordrb Ruby library and the fantastic work Discord team has done to make their system accessible. Thanks to @Falco for helping me with a dependency in an extremely responsive manner.
Additionally, of course, this would not be possible without the amazing plugin ecosystem of Discourse (woo!)
State of these instructions
They will be improved in time and I welcome feedback. There are areas that are bound to be unclear.