LJ Archive

At the Forge

Discourse

Reuven M. Lerner

Issue #241, May 2014

Need a forum or examples of modern Web development? Do you want to learn about good application design? Discourse offers all three, in spades.

Back when I started to use the Internet in 1988, there was a simple way to get answers to your technical questions. You would go onto “Netnews”, also known as Usenet, and you would post your question to one of the forums. There were forums, or “newsgroups”, on nearly every possible topic, from programming languages to religions to humor. It was quite amazing, even back then, to be able to get answers to just about any question you had.

But then the Web was invented, and although it took some time, Usenet became a relic of history. Yes, I realize that Usenet still exists to some degree or another, but let's face it, if you're looking for answers to questions or for an on-line community, Usenet is unlikely to be your first choice. For better or worse, companies like LinkedIn and Facebook have become large players in this field, even though their group and discussion software leaves much to be desired.

And of course, there are other types of forum software. WordPress, which has become an incredibly powerful and flexible CMS and platform, is blogging software at its heart, meaning that it allows you to post to your blog and accept comments. If you want something a bit more interesting than that, such companies as Disqus and LifeFyre offer SaaS forums, letting you turn any page into (potentially) a social community.

And yet, I probably have implemented forum software five to ten times through the years for various clients, and I have installed forum software about the same number of times. Although forum software often is reasonable, it doesn't make me go, “wow”. I run an e-mail list for people who live in my city of Modi'in, and it has become quite large, with 2,800 subscribers and 40–50 messages per day; however, we all agree that e-mail is far from a perfect way to communicate. But, e-mail lists still are far preferable to Web-based forum software, which hasn't ever been exciting or interesting to me.

So, it shouldn't come as a surprise that when Jeff Atwood, cofounder of Stack Exchange and the author of the famous “Coding Horror” blog, announced he was going to make better Web-based forum software, I personally reacted with a shrug. After all, I've used and seen forum software for years. How much different or better could it be?

Well, I can report to you that even though Discourse, Atwood's open-source forum software, is still somewhat unfinished, it already is head and shoulders above other forums I have used, as both a user and an administrator. The fact that it is open source, based on Ruby, PostgreSQL and Ember.js is icing on the cake, making what already was excellent software even better. I've already seen numerous improvements in Discourse since I started to use it, and they just seem to keep coming. For the first time ever, I believe that Web forums can be useful, user-friendly and attractive.

So this month, I look at Discourse—what it is, what it aims to be and what it means regarding not only on-line discussions, but for consumer-facing open-source projects as well.

Installing Discourse

Discourse is an open-source project, hosted at GitHub (see Resources), licensed under the GNU General Public License, version 2. It is backed by Atwood's company, which has the fantastic name of Civilized Discourse Construction Kit, Inc., and it aims to profit through installing and supporting Discourse.

If you're like me, you assume that installing a modern open-source application should be a matter of downloading, installing (perhaps with a separate compilation step first), configuring and then forgetting about it. So, it's a bit of a shock to realize that Discourse is a complex application with many different moving parts that requires some time and attention to install. It's written in Ruby on Rails and Ember.js, and it uses a combination of PostgreSQL (for the main database), Redis and Sidekiq for queuing.

So yes, you can “git clone” the application, and then install the software that way. But, you almost certainly don't want to do that. I did it to get Discourse running on my server, and despite many years of working with these technologies, it still was something of a challenge.

Fortunately, you don't have to do much work. The preferred, recommended way to install Discourse is to use a Docker container, which means that you're no longer installing an application, but rather an entire, preconfigured virtual machine, with all of the settings in place as the original developers intended. The Discourse instructions describe how to install the software on a Digital Ocean machine, but you can use many different server hosting companies.

Once you have installed Discourse, you need to configure it. And it's when you start to configure Discourse that you see it's a very different animal from most open-source projects, in that it aims to make the life of users extremely easy. The thoughtfulness of the design shines through at every instance. The application needs to be configured by setting a number of Ruby variables within the Discourse application, most of which are documented and described within the configuration file itself.

Once you have configured the application and started it up (and I won't go into details here, because the installation guide describes it well enough), you then will have a working copy of Discourse. Make sure that you have configured the SMTP server correctly, and that you are running the Sidekiq message queue, so that when you register as a new user, you will receive the e-mailed confirmation request.

Many things in Discourse are designed quite well, starting with the log in system, which allows you to log in via not only a locally defined user name and password, but also via such third-party services as Facebook and GitHub. (You will need to register for an API key for any service you want to use in this way.) Once you have logged in to your newly created account, the real fun begins, setting up the categories into which topics (postings) can be placed. You can do a great deal of customization or very little. Out of the box, Discourse already works quite well.

Configuration of Discourse is done via the administrator menu (using a link in a slightly difficult-to-find location). The configuration menu is huge, letting you use your Web browser to do everything from setting up headers and footers, to entering your Google Analytics token, to setting your API keys for third-party services.

What really blew me away was the fact that when I went to the main administration page, a panel came up telling me what likely was wrong with my installation. For example, it told me I was using a copy of Ruby whose memory usage was sub-optimal for Discourse. It told me that I had neglected to start up Sidekiq, and it told me how to do that. It even told me that I hadn't changed the logo graphics away from the original defaults.

The design of Discourse, as I mentioned previously, shows that a great deal of attention was spent on small things. When I added a footer to the pages of my copy of Discourse, the in-browser HTML editor automatically added an ending </a> tag following the <a> tag that I had entered. If I want to update just a single field, rather than the entire set of fields on the update-configuration page, I can do that by clicking on a check box.

It's great to see a Web application that isn't only nice for users, but also nice for administrators. By clicking on a check box, you can back up your database automatically on a regular basis. If you want, you also can enter an Amazon S3 bucket name to which your backup will be delivered. The list of thoughtful features, such as these, goes on and on.

And then, of course, you start to use Discourse for discussions and discover all the little things that they added in order to improve the user experience. For example, you cannot enter titles or postings that are too short, and Discourse automatically fixes topic titles that are in all caps. If you reference someone with the @username syntax, his or her personal interactions menu will glow, indicating that there is something to which he or she should respond. And if the user isn't logged in, or doesn't come to the site within a specified time, he or she will receive e-mail, indicating the reference. This provides a great balance between keeping things on the Web and keeping people involved by e-mailing them and inviting them back.

There are lots of other things, some big and some little, which add to the user experience. One of my favorites, as someone who opens many tabs and sometimes forgets what is in each one, is that Discourse keeps track of my writing even if I use multiple tabs. I don't have to worry that opening the same page in one tab will somehow stomp on the posting I already started in another one. That sort of attention to detail, and an understanding of how people actually use the Web with modern browsers, is quite impressive.

Technical Underpinnings

From a user's perspective, Discourse is piece of software. It is easy for regular users, forum owners and moderators alike to configure and use it. But Discourse also is a well-written piece of software, designed for maintainability and long-term growth. Looking at the way it was built can help inform your own work, as you try to create increasingly interesting Web applications. That's because Discourse seems to have been built using most of the latest ideas in the Web application world.

For example, although Web applications traditionally did most things on the server, sending complete HTML pages to the user's browser, that is no longer the case. JavaScript is playing an increasingly vital and dominant role in modern Web applications, and Discourse goes all out on this front, using the open-source framework Ember.js, which aims to make it easy to write sophisticated applications in the browser.

Thus, in nearly every case in Discourse, requesting a URL doesn't result in a complete page of HTML being sent to your browser. Rather, you'll often get a page of HTML without any content. A second, separate request, initiated by Ember, then will request the data that should fill in that page. So, a page refresh often will result in an HTML request followed by a JSON request. If you click on a button or link, however, you're likely not to cause a full page refresh, but rather an Ember action, which will result in an Ajax call to the server, followed by JavaScript-driven changes to the DOM. But as far as the browser is concerned, you have remained on the same page the whole time.

Interviews with Atwood indicate how much he cares about performance, and that is pervasive throughout the site. Although Ruby on Rails has long allowed you to turn an object into JSON with a simple “render json” call, it turns out (and is documented in the Discourse source code) that this is 20% slower than invoking the JSON conversion method on your own. Most applications likely never have noticed this problem, but Discourse, in trying to be speedy, has identified, benchmarked, improved and then documented such issues. In addition, administrators of a Discourse forum automatically have it run with rack-mini-profiler, a Ruby-compatible version of a famous JavaScript plugin that measures the loading speed of the page and of the various Ajax calls executed from within it.

Conclusion

If you need a Web-based forum or are thinking of starting an on-line community, I would argue that you should use Discourse. Despite the early version number, it is stable and useful, and it automatically alerts you when there is a new version to retrieve.

Perhaps the most striking part of Discourse is its attention to details regarding user design. In the open-source world, we're used to thinking in so-called practical terms, often saying that aesthetics aren't necessary, or at least that they can come after correct technical solutions. Discourse is, in many ways, proving the opposite—that you can start off with a relatively limited feature set, but so long as you consider what users want, not what technical functionality you want, your product will succeed.

Indeed, if there is an important lesson I have learned through the years, it's that people aren't interested in functionality, but rather in what they need to make their business, school or home more productive. Features are only important so far as they fix a pressing need.

Bottom line, I encourage you to run, not walk, and try Discourse. Whether you use it on a site, or just read the code to learn how Ruby and Ember can work together, I expect you will get a lot out of it.

Reuven M. Lerner, a longtime Web developer, consultant and trainer, is completing his PhD in learning sciences at Northwestern University. You can learn about his on-line programming courses, subscribe to his newsletter or contact him at lerner.co.il.

LJ Archive