Biz & IT —

Web Served, part 6: Form the forum

Getting started with the Vanilla forum application, with bonus GitHub action.

Web Served, part 6: Form the forum
Aurich Lawson / Thinkstock

We've come a long way since starting this series, and we've got a little further to go before the end. Your Nginx Web server is operational and happily serving out WordPress (hopefully with an eye toward safety and security), but we're going to take things to the next level by setting up a full-blown Web forum.

As with all of our other components, there are many choices. Far and away the most popular (and most well-supported) is phpBB, a mature and extensible piece of software that's used all over the Web, including on Ars Technica's own OpenForum. As long as you stay updated and keep on top of installing all the security updates, it's a good choice for a production website, and it offers an almost ridiculous amount of configurability. We're not going to use it, though. This series is about experimenting and learning new and useful tools. phpBB is most definitely useful, but it's a complex beast and overkill for a personal forum.

Other popular forum application choices are things like Simple Machines Forum and FluxBB (or vBulletin, but it's not free)—we're not going to use those, either. There's nothing wrong with them at all, but they're not my personal choice and they're not what I'm going to talk about configuring.

Instead, we're going to go with Vanilla, a free (as in beer and speech) forum application that's powering a number of forums large and small, ranging from the Chronicles of George forum all the way up to Penny Arcade. Vanilla is fast, open source, and it's got an active developer community. What's more, it's extremely easy to install and configure.

Ah, but it's not going to be that easy, because we're going to get a two-fer in this issue of Web Served: we're not going to just install Vanilla. We're going to install the beta version of Vanilla.

Why beta?

I want to take a few paragraphs to address this, because it's a bit of an odd choice. Vanilla has a perfectly serviceable production release in version, which is unfortunately almost a year old. It works great and many sites use it, but the 2.1 beta version of Vanilla is easily production-ready for a personal website, and it incorporates a truly ridiculous number of improvements over the current release version, inside and out.

I know that the beta is production ready because I'm running it myself. Check out the Chronicles of George forums. I've been using it for almost a full year as it's progressed through alpha to beta, and there are no existing issues with it that will stop it from humming along perfectly well on our test Web server.

If you're not comfortable running beta software in production (though it's arguable whether or not the personal server we've been building as part of this series can be considered a "production" server), then by all means, use the standard version. However, because the beta version really is that much better and really is stable enough to use—and because we're about learning stuff here, not configuring a forum that will support a million users under load—we're going with 2.1.

The prerequisite: Git

We're entering adventurous territory and installing the beta instead of the release, but first we need to first install the means by which we're going to grab Vanilla: Git. Git is a version control system—a tool which lets developers track the changes made to a project's source code over time. A VCS like Git makes copies of a piece of code every time it's changed, saving old revisions and letting a programmer see how his or her code is evolving and allowing them to revert back to a previous version if they make an error. A VCS also lets teams of programmers "check out" blocks of code to work on, ensuring that different team members aren't accidentally working on the same thing at the same time and clobbering each other with edits.

The Vanilla team uses Git to store the Vanilla source code, keeping it in a Web-based Git repository on GitHub, an enormous site that hosts Git projects of every shape and size. In order for us to use the beta version of Vanilla, we're going to install the Git client on our Linux Web server and use it to clone the Vanilla repository down onto our Web server. That will get us a copy of the current Vanilla code. It will also allow us to easily update it as time goes on.

Fortunately, as with so many of the tools we need, installing Git takes only a single command:

sudo aptitude install git

Cloning Vanilla with Git

Once Git is installed, we will clone the "Master" branch of the Vanilla repository. The repo is divided up into several different branches, each of which contains different stages of the project; we want "Master" because it holds the latest complete Vanilla 2.1 release. Features are authored and tested in the other branches and merged into the "Master" branch when the development team has determined that they're relatively stable.

If you look at the master branch, you'll notice that it appears to contain a set of files and directories; these are the files and directories that actually make up Vanilla. We're going to use the git clone command to make an exact copy of the repository on our Web server, underneath the Nginx Web root (after first launching a root shell so that we don't have to keep prefacing things with sudo):

sudo /bin/bash
cd /usr/share/nginx/html
git clone vanilla
chown -R www-data:www-data vanilla

The git clone command takes as arguments the repository to clone and the directory into which you want to put the files; we're using vanilla as the name of our local directory, which Git will create for you. You can name it whatever you'd like (forum or cheesegrater would work equally well). The last command ensures that the ownership of the Vanilla directory and all its contents is set to the Nginx account instead of root.

A note on the cloning process: we're not actually making a copy of the files in the Vanilla Git repository, but rather creating our own full code repository, complete with versioning. If you're not going to be doing any hacking on the Vanilla core files, then this doesn't really make much difference, but the framework is all there. Later, we'll cover how to update Vanilla, which will involve a pull from the Vanilla Master branch on GitHub—Git will look at the differences between your local Vanilla setup and the files in the Master branch and retrieve the updates automatically.

SQL configuration

Much like with our previous WordPress setup, getting Vanilla working will require us to create an SQL database for it and a user and password for Vanilla to use with that database. Log in to SQL Buddy, then create a database named "vanilla" using the "Create a new database" section on the home screen. Make sure to change the "Charset" field to "utf8" before hitting "submit."

Adding our Vanilla database. Don't forget to change the encoding type to utf8.
Enlarge / Adding our Vanilla database. Don't forget to change the encoding type to utf8.
Lee Hutchinson

After the database has been created, click the "Users" menu item at the left of the window, and create a user. As with our previous WordPress user, we want to make sure to only grant this user privileges to interact with the Vanilla database, so change the "Allow access to" radio button from "All databases" to "Selected databases," and then only check the "vanilla" box. After this is set, click "submit."

Adding our Vanilla database user.
Enlarge / Adding our Vanilla database user.
Lee Hutchinson

Nginx and PHP configuration

Vanilla is a PHP application, so we're going to need to set up a PHP location for it so Nginx knows what to do with Vanilla's PHP files.

You can choose whether or not you want to serve Vanilla on its own virtual host (like or in a subdirectory on an existing vhost. We're going to serve out of a subdirectory, because that's what we're already doing with our WordPress blog. However, it's not that much extra work to have Vanilla served out of its own host.

Open up your /etc/nginx/sites-available/www virtual host file for editing. Add the following three locations to the file:

location /vanilla/ {
  try_files $uri $uri/ @forum;
	deny all;

location ~ /vanilla/.*\.php$ {
try_files $uri =404;
include fastcgi_params;
	fastcgi_pass php5-fpm-sock;
	fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
	fastcgi_intercept_errors on;

location @forum {
	rewrite ^/vanilla/(.+)$ /vanilla/index.php?p=$1 last;

(If you're using HTTPS, you'll need to duplicate these three locations in the HTTPS section of your vhost file, with fastcgi_param HTTPS on; added to the second.)

Two of these blocks should be looking pretty familiar by now. The first defines a location for our forum and sets it to only be visible on our LAN for now—you'd remove this when you want to take your site public. The second sets up our PHP handler, telling Nginx to take requests for files that match its path regex and send them to PHP-FPM to be processed.

One notable line in the PHP handler is fastcgi_split_path_info. This is particularly important because with Vanilla (and other PHP apps, too), request URLs can contain not just files but also arguments used by the forum application. This line tells Nginx and PHP what parts of the URL contain the actual path and what parts are arguments.

The third location is called a named location. It's prefaced with an "@" sign to set it apart. Named locations aren't intended to point to actual locations, but rather as shortcuts to be used during rewrites. Here, we're using it as the final catchall argument in /vanilla location's statement.

Why? There are two main reasons, but the biggest is to enable pretty URLs. Vanilla, like most PHP applications, has ugly URLs that are usually made up of a PHP file and a bunch of arguments, but we're going to make them human-readable instead, and that requires doing a bit of rewriting. The forum has a config file option to enable pretty URLs—we're going to flip it on in just a moment—but it needs the Web server's cooperation in order to work, and this is how we supply that cooperation. The rewrite line takes whatever is in the URL after /vanilla/ and repackages it behind the scenes as an argument after index.php. Rewrites are quite common in URL prettifying.

There are many ways to tackle this particular rewrite, but the second reason we're doing it this way specifically is so that we can serve up forum-branded 404 pages when files aren't found. This is possible because of how try_files works. This directive saves a huge amount of time and effort and if statements (which is good, because you want to avoid using if with Nginx). You can specify try_files once on the root of the site, and again on any other locations you've got. The directive tells Nginx what to do when it looks for a URL; in the way we're using it, we're telling Nginx to look for a file that matches the URL's name, and if it finds nothing to then toss a slash on the end of the URL and look for a directory with that name, and if it finds nothing to then pass the entire URL to the @forum named location. That location, as we've seen, sticks the request on the end of index.php and runs it. The forum takes care of supplying its own 404 pages because anything you put into the URL bar will be parsed through PHP. If it corresponds to something Vanilla understands, it will serve the object; if not, it will serve its own 404 page.

There's more Nginx configuration to be done to add a dash of security and to make the URLs pretty, but we'll hold off on that until the end. First, we're going to finish up and get Vanilla operational. Make sure to have Nginx reload its config files before you proceed so that the changes will be made active:

/etc/init.d/nginx reload

You must to comment.

Channel Ars Technica