HHVM on Lighttpd – Walk in the Park

Just switched this server (dedi.nexisonline.net) to HHVM, a recode of PHP by Facebook. The process went smoother than expected, although I switched the ChanMan/testing server to HHVM a while ago, and therefore had some prior experience.

Unfortunately, HHVM has rather piss-poor documentation on how to get it running on Lighttpd, which is fairly odd, considering they have docs for Apache and nginx. So, for those looking for help, here’s how to get HHVM working under lighttpd in FastCGI.

Installation

The first step, obviously, is to back up your settings.  While HHVM is designed to be backwards compatible and have parity with PHP, some things are different (notably the configuration files), and you’ll want to have them on hand in the event they need to be referenced, or in case everything goes to hell and you need to re-install PHP.

Next, install HHVM from the pre-packaged binaries on the site.  You may be tempted to compile it, but when I gave it a shot, the process of getting a build environment set up was a nightmare of its own:  Numerous manual downloads of dependencies, conflicts with OS libraries, and many other fun issues.  So, I just decided to roll with the prepackaged binaries for Jessie.  (I’ve also tested this on Wheezy with identical results.)  For lighttpd, do NOT run the FastCGI installation script it tells you to run after installing the package, as it is only made to handle nginx and Apache.

Now, create /etc/lighttpd/conf-available/15-fastcgi-hhvm.conf with the following contents:

# -*- depends: fastcgi -*-
# http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs:ConfigurationOptions#mod_fastcgi-fastcgi

fastcgi.map-extensions = ( ".php3" => ".php", ".php4" => ".php", ".hh" => ".php" )

## Start an FastCGI server for hhvm
fastcgi.server += ( ".php" => 
	((
		"socket" => "/var/run/hhvm/server.sock",
		"max-procs" => 1,
		"bin-environment" => ( 
			"PHP_FCGI_CHILDREN" => "4",
			"PHP_FCGI_MAX_REQUESTS" => "10000"
		),
		"bin-copy-environment" => (
			"PATH", "SHELL", "USER"
		),
		"broken-scriptfilename" => "enable"
	))
)

You’ll notice this is pretty much identical to the old PHP module, and you’d be correct. However, HHVM runs as its own service, so all the launch arguments have been removed.

Configuration

Now, you need to edit /etc/hhvm/server.ini to read:

; php options

pid = /var/run/hhvm/pid

; hhvm specific 

; This is the important part, and needs to be identical to the "socket" directive in your fastcgi.server definition for HHVM.
hhvm.server.file_socket = /var/run/hhvm/server.sock
hhvm.server.type = fastcgi
hhvm.server.default_document = index.php
hhvm.log.use_log_file = true
hhvm.log.file = /var/log/hhvm/error.log
hhvm.repo.central.path = /var/run/hhvm/hhvm.hhbc

Now it’s time to get everything up and running.

Startup

# Enable HHVM module:
$ sudo lighttpd-enable-mod fastcgi-hhvm

# Disable PHP, if needed:
$ sudo lighttpd-disable-mod fastcgi-php

# Use HHVM as our PHP CLI (optional):
$ sudo /usr/bin/update-alternatives --install /usr/bin/php php /usr/bin/hhvm 60

# Start up HHVM at server startup:
$ sudo update-rc.d hhvm defaults

# Start up HHVM and restart Lighttpd:
$ sudo /etc/init.d/hhvm start && /etc/init.d/lighttpd restart

You should now be up and running. Remember to tweak /etc/hhvm/php.ini as desired, such as turning on error display and setting PHP include paths.