blog

archives

Beginner’s Guide to Creating Discourse Plugins

Jeff Atwood April 14, 2016

Part of our important work with Rails Girls in 2014 and 2015 was not just to mentor and encourage new developers, but also evolve Discourse into a platform that’s generally friendly and easy for developers to build on.

We’ll be working with the Rails Girls project again in 2016, and this year will be our first with Google Summer of Code. As we work with novice developers and help them get comfortable building on Discourse, we get better at it, and our Discourse extension points and plugin story continues to improve.

start-scrabble

For example, last year Robin put together a great six part series in the #howto category on meta, the Beginner’s Guide to Creating Discourse Plugins:

  1. Introduction
  2. Plugin Outlets
  3. Custom Settings
  4. Git Setup
  5. Admin Interfaces
  6. Acceptance Tests

This year, we’ll work with our GSoC teams and Rails Girls to dogfood these plugin tutorials even more and further refine them. They’ll be building cool new features and plugins with stuff like webhooks, canned responses, feature voting, low-end device pure HTML mode, better chat system hooks, user-centric activity digests, better color theme previewing, and so on.

In the past, we’ve hosted a general discussion topic on meta for these groups — here’s the one we used for Rails Girls in 2015 — and we encourage the whole community to collaborate on what’s being built and provide feedback alongside us. That is, after all, exactly what Discourse is designed for — collaboration through discussion! Keep an eye out for the upcoming 2016 discussions on meta in the next month or two.

This year, we’ll also be setting up Digital Ocean droplets with test Discourse instances for the teams to experiment and install their plugins on. Of course, anyone can install Discourse in the cloud in 30 minutes, but we want to make sure the post-install plugin installation and troubleshooting story is as clear and problem free as it can be, too.

If you too are looking to build on the Discourse platform, I hope these Beginner’s Guides to Creating Discourse Plugins are useful – please let us know how they can be improved!

Leave a reply

Discourse 1.5 Released!

Jeff Atwood April 1, 2016

We’re proud to announce that today marks the release of Discourse 1.5! This was a huge release that took us almost 7 months to build:

5× Faster Topic Page

Perhaps the most significant improvement in this release is a dramatic overhaul of our topic page for a 5× speed improvement. That’s right, the topic page – the page where most people will spend most of their time in Discourse – is a whopping five times faster!

Some before and after benchmark timings from Robin’s detailed blog post:

Large topic, initial visit

Desktop Nexus 7 Nexus 6p
633ms 4078ms 1248ms
120ms 636ms 248ms

Large topic, repeat visit

Desktop Nexus 7 Nexus 6p
429ms 2757ms 710ms
69ms 350ms 152ms

For those of you keeping score at home, that is indeed 5× faster on all devices on average, and an incredible 6-8× faster on older Android devices.

Improved Badges

Discourse’s badge system is a fun way to teach community members not only how the site works, but also what positive community behaviors we encourage. In this release our Badge system got greater prominence with a much needed visual overhaul, as well as improved long descriptions that better explain what each badge is for.

discourse-badges-v15

We also introduced a number of new badges to encourage regular use of likes, and liking in return:

  • Out of Love — Used 50 likes in a day
  • Appreciated — Received 1 like on 20 posts
  • Gives Back — has 100 liked posts and gave 100 likes
  • Higher Love — Used 50 likes in a day 5 times
  • Respected — Received 2 likes on 100 posts
  • Crazy in Love — Used 50 likes in a day 20 times
  • Admired — Received 5 likes on 300 posts
  • Empathetic — Has 500 liked posts and gave 1000 likes

Share the love!

User Summary Page

While Discourse has top users and top topics, one thing that’s been missing is a way to see an individual user’s top contributions to the community. But now you can! Just visit the Summary tab on any user page to check out their “greatest hits”:

discourse-user-summary-v15

We’ll continue to refine and improve these summaries to make them more interesting, and better show off your most interesting contributions to the discussions.

Customize ALL Text and Email Content

This one has been requested forever, and was a ton of work. Did I mention this was a long release cycle? But it was all worth it because you can finally edit any – literally any – text or email content in Discourse and customize it exactly how you want.

Want topics to be “threads”? Users to be “funkatrons”? Like to be “brofist”? Well, Discourse is your huckleberry. Go forth and customize any text you see on the screen, anywhere, in Admin / Customize / Text Content.

Group and Category Mentions

You know how you can type @username to mention someone, and have them get notified, in Discourse? Pretty cool right? Now you can do that very same thing with @groups too, if the group settings allow. Similarly, you can mention #categories to get a handy list of categories and a quick link to any category. (Category mentions don’t ever generate any notifications, though, because that would be a little nuts.)

Better Incoming Email Support and Group Private Messaging

One of the primary targets of Discourse is mailing lists. Whenever information is getting stuck in those mailing list private email silos, we think you’re better off sharing that information with others.

But there are a few cases where you might not want these emails to be public. One of those use cases is a shared support email inbox. Such as … the one we run at team@discourse.org. We belatedly realized we should be feeding our own incoming support, feedback and sales emails into our Discourse as group private messages that are visible to our entire team.

While we dogfooded this feature over a period of months, we vastly improved our incoming email handling and group private messaging. We also now show additions and removals to private messages directly in the stream, so you can better tell who you’re talking to in a private message:

discourse-invite-stream-notify-v15

Please see the detailed incoming mail howto Régis put together for more details!

Mobile Editor Toolbar and Preview

Our mobile editor was enhanced to include a toolbar (if your device is large enough to display it, sorry iPhone 4) and a preview button. To show or hide the toolbar, tap the hamburger icon at upper right.

discourse-mobile-editor-v15

Now while on mobile you can more easily do things like add emoji, turn your post into a private whisper, or see a preview of your post formatting before you reply.

And so much more

These are just the major highlights in 1.5 — there are literally hundreds of other tiny improvements, refinements, and bugfixes in 1.5 that we aren’t covering here, but are in the full release notes.

Easy One Click Upgrade

It’s safe to say that 1.5 is the best release of Discourse ever. Upgrade your Discourse instance today to get all these great new features via our super easy one click admin updater. It’s linked right from your dashboard:

If you don’t have a Discourse to upgrade, why not? Install it yourself in under 30 minutes, or get a free 14 day hosting trial!

Thank You

As usual, we’d like to first thank our customers for your support, and the overall Discourse community for their many contributions toward this release — whether it was in pull requests, feedback on meta.discourse, or our personal favorite, feedback based on participation in your very own Discourse community.

In particular, we’d like to highlight significant pull request contributions in this release from:

For insight into what’s coming up in future releases of Discourse, keep an eye on the releases category at meta discourse.

5 Replies

Switching Your Discourse from Mandrill to Mailgun

Jeff Atwood March 28, 2016

Self-hosted Discourse requires email to function, so we’ve always had a symbiotic relationship with third party email providers. In the past we’ve recommended Mandrill, we use it ourselves for some of our sites, and we’ve had nothing but positive experiences with Mandrill … until now. On February 24th, Mandrill announced they are essentially closing the Mandrill service forever as of April 27th, 2016.

Going forward, all Mandrill users will be required to have a paid monthly MailChimp account and verify ownership of all sending domains. Here’s the timeline: Starting 3/16, all new Mandrill users will create accounts through MailChimp, and current Mandrill users can merge their existing Mandrill account with a monthly MailChimp account. Current users will have until 4/27 to merge their accounts.

Technically you can transition to their MailChimp provider, but it’s a massive increase in monthly costs – from free (for 12,000 or fewer emails per month) to about $40 per month. That’s four times as much as Digital Ocean charges for a basic $10/month Discourse host VM, just for sending email!

no-mailchimp

While you can “upgrade” your Mandrill account to MailChimp, we don’t recommend that, unless you feel like paying $40 per month for the privilege of sending a few emails. There are several other reliable third party email providers who offer similarly free plans below a reasonable send limit:

We’ve heard positive things about all of these services, but we have the most experience with MailGun, so that’s what I’m going to walk through here. The steps will be roughly similar for any third party email service.

1. Sign up with Mailgun

Go ahead and create your Mailgun account. No credit card is required; you can optionally add one at signup if you want to ensure continuity of service if you might exceed the allowed 10k emails per month — that’s 333 emails per day, on average.

However, in addition to a verified email address, a valid telephone number is required and a SMS verification will be sent, so be ready.

2. Add the domain to your account

In MailGun, under your Domains tab, add your Discourse domain in this form:

discourse.example.com

Note that the email must come from `@discourse.example.com` for this to work, so be sure that your Discourse site settings for mail include that domain, particularly under notification email:

discourse-notification-email

Be sure that says noreply@discourse.example.com and that the domain matches your email. Email is always judged by the domain it was sent from!

3. Update DNS records to validate your domain for email

If you visit your domain page in MailGun, you’ll see a summary of the necessary DNS changes to verify your domain.

mailgun-dns-changes

You should generally make these DNS changes at the same place you purchased the domain name from, unless you’ve transferred DNS functions to somewhere else. You need to add or update two TXT records here, one for SPF and one for DKIM. Here’s what those two TXT records look like in CloudFlare DNS:

mailgun-dns-entries-cloudflare

Once you’ve done that check back on your domain page using the Check DNS Records Now button to verify that Mailgun sees the change. This change may take up to 24 hours to propagate, so be patient. It definitely took a few hours in my testing. Mailgun will email you once the domain is fully verified.

mailgun-verified-email-notice

Note that until you make these DNS changes to verify your domain, you will only be able to send email to the single email address that you signed up with!

4. Log in via SSH and edit your Discourse config

Now we’re ready to plug in the credentials for our Mailgun account into Discourse. SSH into your server using your SSH client of choice.

Once you’re logged in and at the SSH command prompt, edit the app.yml file:

cd /var/discourse
nano containers/app.yml

You’ll need to change three DISCOURSE_SMTP lines, using the account information provided for the domain on the MailGun domain page:

DISCOURSE_SMTP_ADDRESS: smtp.mailgun.org
DISCOURSE_SMTP_USER_NAME: postmaster@discourse.example.com
DISCOURSE_SMTP_PASSWORD: ac9e7725d9c65fdf47dccea0f16838b0

Once you finish, rebuild your Discourse to latest. Don’t worry, this won’t delete anything! It will, however, take anywhere from 4 to 10 minutes depending on the speed of your server, so plan for a bit of downtime.

git pull
./launcher rebuild app

Once the build completes, you’ll be at the command prompt again and your Discourse site will be rebuilt and live. You shouldn’t see any errors, but if you do, scroll up to view them, and try editing app.yml again.

5. (Optional) Spring Cleaning

While you are logged in via SSH I strongly recommend you do a bit of yearly spring cleaning. Bear in mind, this is totally optional, feel free to skip to the next step if you’re in a hurry and just want to get your mail fixed. But … you might as well since you’re right here. It’s easy, I swear!

If you’re using our recommended Ubuntu 14.04 LTS, download the latest Ubuntu updates and install them:

apt-get update
apt-get dist-upgrade

Clean up leftover backups from old automatically installed Ubuntu updates to free up some disk space. The savings can be substantial, multiple gigabytes:

apt-get autoremove
apt-get autoclean

Clean up any old Docker containers left around by your previous Discourse upgrades, which can also be multiple gigabytes:

./launcher cleanup

6. Send a Test Email

To verify that everything is working properly, visit your Discourse Admin dashboard, under Emails, and read the summary. Does it match what you entered in app.yml?

discourse-admin-email

If everything here matches what you entered, down at the bottom, enter your email address – the same one you originally signed up with on MailGun – and press the Send Test Email button. If this email arrives in your inbox, you’re good. Once your domain is validated, you should be able to send a test email to any email address from here and it should arrive.

If the mail doesn’t arrive, check the Logs tab for your domain to make sure that your settings were at least correct enough for your Discourse server to talk to MailGun:

mailgun-logs

If you don’t see a log entry here, it means you probably messed up the SMTP username, password, or address settings in app.yml, so double check those.

Good luck, and I hope this guide helped! We do apologize for the inconvenience, but MailChimp decided to effectively discontinue their free Mandrill service on rather short notice.

As a gesture of goodwill, if you have an existing Discourse site and are having trouble with this, assuming you have already completed steps 1-3 we can assist with the Discourse SSH sections (steps 4 and 5) if you email us at team@discourse.org with SSH login credentials. Please note that we cannot help until you have performed steps 1-3 as they are prerequisite steps that are highly specific to you, your email address, your telephone number, and your domain name.

7 Replies