Running Nginx With Ejabberd On Ubuntu 8 Server (Hardy Heron)

Thursday, May 15 at 9:13 p.m.

An Author's Apology

I don't ordinarily write technical posts like this. Most of the people who I know who know about this blog don't care about XMPP, ejabberd, Nginx or any of the other technology I'm about to write about. Sorry about that. There are a few people out there who will be interested. And this is partly for you, but it's mostly because I couldn't find any documentation about how to do this in the wild. This isn't exactly "Expertsexchange" type stuff here. Though it isn't too complicated.

Seriously. If you've set up ejabberd, and you know how to set up Nginx, you might as well just move on. But if you're curious about how both these awesome systems can work together today, read on, brave one, read on.

What the? Huh?

So you may have noticed that there's a red icon in the upper left part of this site. It says chat!. When you click it, you're dragged all the way to the bottom of this page. If you enter a name (no spaces, please) and click "Chat!" after a few seconds you'll be shown a form that says "Say: [TEXTFIELD]". If you type something in to the text area and hit enter, you've just sent me an instant message. Go ahead. Try it, then come back to this article. If I'm awake and online, I'll respond. You'll see the response appear on the page. Yes. You are chatting. With me.

Pretty cool, huh?

Ok hotshot, how'd you do it?

I hoped you would never ask! I mean, I thought you would never ask! Let me tell you, step by step:

1. Install ejabberd
2. Configure ejabberd
3. Configure Nginx
4. Javascript

Installing ejabberd

This was pretty easy. I'm running an Ubuntu VPS on ksmooney.com, which I've just recently upgraded to Hardy Heron. Here's how you install ejabberd in ubuntu:

    sudo apt-get install ejabberd
    (type your password)

Configuring ejabberd

Then wait while everything gets installed. I had a scary moment when lilo(!) told me that it was getting installed. Everything seems cool so far, but I haven't had to restart my server since the install on Saturday, so even my mileage may vary. Ok. Now that you've got ejabberd installed, you'll need to set it up. In your favorite text editor, open the config file as root:

    % sudo vim /etc/ejabberd/ejabberd.cfg

The only crazy thing here is that the configuration file is written in erlang. Don't fret - it's pretty straightforward. To do the most basic setup, just change the first few lines. You'll need to change the server and you'll need to change the admin user. Here's what the first bit of the config file should look like:

    %% Admin user
    {acl, admin, {user, "root", "ksmooney.com"}}.

    %% Hostname
    {hosts, ["ksmooney.com"]}.

Note the periods at the ends of each line. Also note that the percent symbol is erlang-ese for a comment.

Ok - now that you're ejabberd is configured, restart the server:

      /etc/init.d/ejabberd restart

Once the server is restarted, try to log into it with Adium or Pidgin. You'll want to use your chat client to register a new user on the server - as a matter of fact, register the admin user (that you configured in the ejabberd conf above) while you're at it. It'll come in handy later.

If you can successfully log into your new jabber server, things are looking good! If not, review your configuration (don't forget the periods at the ends of the lines) and try again.

Also, your new jabber server has exposed a new port, 5280 for XMPP messages that are passed over an HTTP transport. Additionally, you've got a handy administrative interface at that port too.

To perform http polling on port 5280, you'll have to send XMPP messages to http://yoursite:5280/http-poll/

This is just fine, unless you want to use, say, AJAX to build an in-website chat client, since AJAX requests must be made to the server and port that the page was downloaded from. Since my home page lives on port 80, I can't talk to port 5280 using XMLHttpRequests. To get around this problem, we just have to set up a proxy in nginx.

Configuring Ngnix to proxy to your ejabberd server

This is pretty easy. First, add an upstream server to the web site that you're currently working on. Since I only have the default website, I'll use that:

    vim /etc/nginx/sites-available/default

Add the following configuration stuff to the beginning of that file:

     upstream chatserver {
          server 127.0.0.1:5280;
     }

Then, navigate to your http server and add the following chunk of code:

    location /http-poll {
            proxy_set_header Host $http_host;
            proxy_redirect false;
            proxy_pass http://chatserver;
            break;
    }

Ok - see how the location is /http-poll? That's what your ejabberd server wants the polling URL to be - I tried to map the polling URL somewhere else, but that failed. Anyways, the only other really critical thing to notice here is the 'proxy_pass' statement - that just says, 'pass all web traffic for the previous domain to the upstream proxy that I called chatserver.'

Now that you've modified the Nginx configuration, go ahead and restart the server.

    % sudo /etc/init.d/nginx restart

Congratulations! You now have Nginx set up to proxy to ejabberd! No compiled modules necessary!

What Next?

Well, the next thing to do would be to build the client - I used the awesome JSJaC Javascript XMPP library along with jQuery to build the chat client. You can review the code if ya'll want. In the next article, I'll talk about how to use JSJaC to build a super simple simple jabber clientt in javascript.