Getting Started with HHVM

In this section you will learn how to set-up NGINX with HHVM and MongoDB. However, this tutorial is not meant to be an all inclusive guide on how to run NGINX and HHVM in a production environment.

In this tutorial, we will be using a Debian system with NGINX installed through apt-get and HHVM installed from source or pre-built packages into /usr/local/hhvm/3.9.1 (with the binary located at /usr/local/hhvm/3.9.1/bin/hhvm).

Installing NGINX

We simply install NGINX by running apt-get install nginx-full. If NGINX fails to start after installation, it is likely that you already have another web server (e.g. Apache) running on the same port. In that case, you will see the following lines in /var/log/nginx/error.log:

2015/09/29 10:19:27 [emerg] 22445#22445: bind() to 0.0.0.0:80 failed (98:Address already in use)
2015/09/29 10:19:27 [emerg] 22445#22445: bind() to [::]:80 failed (98: Address already in use)

To resolve this, you can either change the default port for NGINX or Apache, stop the Apache process with service apache2 stop, or remove Apache entirely with apt-get remove apache2.

Installing HHVM

This tutorial is written from the perspective of an extension developer, so we've installed HHVM from source to faciliate patch development and ensure that debug symbols are available. That said, the folks at Facebook also provide pre-built packages, which is probably what you will want to use in production and development. You can find installation instructions for these packages on the » HHVM Wiki.

You will need to install both the the hhvm and hhvm-dev packages. The latter is needed so that we can compile the MongoDB HHVM extension later on.

If you are compiling HHVM from source, you will need to create /var/run/hhvm:

sudo mkdir -p /var/run/hhvm
sudo chown www-data.www-data /var/run/hhvm
sudo mkdir /etc/hhvm
sudo touch /etc/hhvm/php.ini
# So that you don't have to ``sudo`` to edit the file
sudo chown derick /etc/hhvm/php.ini
# To see whether it actually works
echo "date.timezone=Europe/London" >> /etc/hhvm/php.ini

HHVM should be started as the www-data user. For the purposes of this tutorial, we can run it in the foreground in server mode as follows:

sudo -u www-data -s /usr/local/hhvm/3.9.1/bin/hhvm \
 --mode server \
 -vServer.Type=fastcgi \
 -vServer.FileSocket=/var/run/hhvm/sock

Making NGINX Talk to HHVM

Once HHVM runs, we need to tell NGINX how to talk to HHVM for executing .php files. Although this is perhaps not the cleanest approach, you can add the following snippet to /etc/nginx/sites-enabled/default, just after the location / { … } section:

location ~ \.php$ {
   fastcgi_pass unix:/var/run/hhvm/sock;
   fastcgi_index index.php;
   fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
   include fastcgi_params;
}

After adding that snippet, you should restart NGINX:

sudo service nginx restart

To confirm that everything works so far, we will create a project directory with an index.php file that calls phpinfo():

  • Create the project directory: sudo mkdir -p /var/www/html/my-first-project

  • Change permissions to your user and the www-data group: sudo chown derick.www-data /var/www/html/my-first-project

  • Create the file /var/www/html/my-first-project/index.php. From now on, I will not include the full path /var/www/html/my-first-project/ when I mention file names. Put the following content in this file:

    <?php
    phpinfo
    ();
    ?>

Now, in your browser, request the page http://gargleblaster/my-first-project/index.php (but adjust the hostname). This should then show a page starting with "HHVM Version 3.9.1" followed by several tables with information.

Installing the MongoDB Driver for HHVM

The MongoDB driver is the part that links up the PHP in HHVM with the database server. To install and register the driver with HHVM, you need to follow the steps in Manually Installing the MongoDB HHVM Driver.

After you have installed and enabled the extension, HHVM will need to be restarted. If you have HHVM running in the shell from earlier, stop it with Ctrl-C and restart it again as above:

sudo -u www-data -s /usr/local/hhvm/3.9.1/bin/hhvm \
   --mode server \
   -vServer.Type=fastcgi \
   -vServer.FileSocket=/var/run/hhvm/sock

In order to test that the driver is loaded, edit the index.php file and replace its contents with:

<?php
var_dump
(phpversion("mongodb"));
?>

This should output something similar to:

string(5) "x.y.z"

Further Reading

Continue this tutorial by jumping to Using the PHP Library for MongoDB (PHPLIB).