Building nginx to use WebSockets

With our Play! applications, fast real time server ↔ client communication is very important. Fortunately, Play! has a great API for handling data reactively with Iteratees, Enumerators, and Enumeratees.

Fortunately, nginx, which is often used as a proxy to Play!, just released WebSocket support in version 1.3.13. It’s still a development release, so many package managers don’t have a build yet.

To build Nginx 1.3.13, grab the source from the nginx download page. Be sure to make backups of your current nginx configurations, as the make install later will overwrite them. On our EC2 instance, we made backups of /etc/nginx/ and /etc/init.d/nginx.

If you would like to change the display name of your server, now’s a great time. Edit src/http/ngx_http_header_filter_module.c lines 48 and 49 to be whatever you want. Next, run ./configure in the nginx source directory. You can set several preferences here, such as config locations, log paths, etc. To keep yours the same as before, consult the Install Options page in the nginx wiki. We used ./configure --with-http_ssl_module --prefix=/etc/nginx --sbin-path=/usr/sbin/nginx --conf-path=/etc/nginx --pid-path=/var/run/nginx.pid --error-log-path=/var/log/nginx/error.log --http-log-path=/var/log/nginx/access.log --user=nginx.

Next, issue make, then shut down your nginx server with service nginx stop on many distributions. If you were previously using a package manager’s build, you can safely uninstall it now. Run make install, then replace your old 1.2.x configuration files, and bring the server back up. If all’s good, you should be back up and running with nginx 1.3.13.

To enable websockets, add the following to your approperiate server configs (setting your websocket path correctly):

  location /ws {
    proxy_pass http://yourServerAlias;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
  }