HHVM Nginx WordPress a working tutorial

What is HHVM ?

HHVM stands for HipHop Virtual Machine.It is the technology used by Facebook to power their own website.You can also power your website with HipHop virtual machine.It can only be used if your website is powered by PHP.Currently it may not work with all the PHP based content management system out there.It was not compatible with WordPress also.But with WordPress version 3.9 things have changed.Now WordPress and HHVM are fully compatible.

I tried configuring this website to use HHVM.I am currently using PHP5-FPM along with ngx_pagespeed on this website.For almost all website out there PHP5-FPM will work fine along with any decent caching solution.I have written a separate tutorial on ngx_pagespeed.PHP5-FPM and Nginx combination is working great for me.But I thought to give HHVM a try.It is worth mentioning that I have tested it successfully on this website.

I decided to keep my ngx_pagespeed setup as it is and replace PHP5-FPM with HHVM.I was not sure whether ngx_pagespeed will create any problem or not.But in theory it should not make any problem.In the end my assumption was correct.ngx_pagespeed worked well with HHVM.The steps mentioned below was carried out for this website and on live environment.I would like to mention that you can use it only if you are using VPS or dedicated server.

HHVM Nginx Configuration

Installing HHVM

The HHVM website provides detailed commands to install from source.I will not cover them here.I will cover instructions for Debian 7.In case you are using different distro you can read the installation instructions in this post.

The instructions on HHVM site does not mention commands in second line (given below).This command is necessary.You will not be able to upgrade the packages later with apt-get upgrade command.So it is better to add the key.

Debian 7

echo deb http://dl.hhvm.com/debian wheezy main | sudo tee /etc/apt/sources.list.d/hhvm.list
wget http://dl.hhvm.com/conf/hhvm.gpg.key | sudo apt-key add hhvm.gpg.key
sudo apt-get update
sudo apt-get install hhvm

For installation I would recommend using pre built packages.It makes installation process easy.You do not have to deal with dependencies related problems.I faced no problem installing it on my Debian server.After installation is complete you will see messages as shown in below image.HHVM provides post installation commands you might have to run.This information is important.You can take screen shot of it for reference.

HHVM Nginx Installation

Configuring Nginx

Now to configure your Nginx web server run below command


Running this command creates hhvm.conf file inside /etc/nginx directory.Also it adds include hhvm.conf line in every server block of your default file in /etc/nginx/sites-available/ .Now if there is no default file in /etc/nginx/sites-available/ then the inlcude lines are not added in server blocks.You will have to add them manually.You should check the files inside /etc/nginx/sites-available/ and add below lines any where inside Server block

server {
	# There will be many lines above or below You just need to add below line in every server block of the file
	include hhvm.conf;

After adding this line you should comment out below lines.In Nginx configuration # is used to comment out the lines.You basically need to comment out all the lines between location and closing }.These lines are used by PHP5-FPM.So we are commenting this out.HHVM will use configuration inside hhvm.conf.

# Pass all .php files onto a php-fpm/php-fcgi server.
#location ~ .php$ {
#	fastcgi_split_path_info ^(.+.php)(/.+)$;
#	include fastcgi_params;
#	fastcgi_index index.php;
#	fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
#	fastcgi_pass;

Testing Configuration

Now configuration part is over.We need to test the configuration.As I already had my website running.It was easy for me to test the configuration.We will reload Nginx configuration to test and try to browse the website.

nginx -t
/etc/init.d/nginx reload

The first command will test the configuration for syntax errors.The second command will load Nginx configuration.Now you can browse your website and see if there is no Nginx error.If there is anything wrong then you will get 502 error.This is it.You do not have to make any additional changes.

You can also test if Nginx is using HHVM or not.To test this create a file hhvm.php in /usr/share/nginx/html (your web root directory).After creating that write below code in it

if (defined('HHVM_VERSION')) {
 echo 'Hip Hop Virtual Machine is working';
else {
echo 'Hip Hop Virtual Machine is not working';

Now browse the file in browser (your-domain-name.com/hhvm.php).You should see the output Hip Hop Virtual Machine is working.If the output is Hip Hop Virtual Machine is not working then you check the errors in HHVM log files or Nginx log files.HHVM configuration files and log files are explained in next section.Nginx log files are located in /var/log/nginx directory.To view Nginx errors you can use below command

tail -f /var/log/nginx/error.log

PHP5-FPM handling

This section is important.If you have PHP5-FPM installed on your server and is working then this section is important for you.I was using PHP5-FPM on my server.I installed Hip Hop Virtual Machine on top of it.The above setup was working fine for me but after few seconds I was getting 502 error.After jerking my head few times I recalled PHP5-FPM is active on my site.

It will not serve the pages.But it will eat up the resources.So I used below command to stop it.In case you have PHP5-FPM on your website then stop it before following steps mentioned in HHVM and Nginx configuration and running it.

service PHP5-FPM stop

You can remove it from your server.But you should not remove it immediately.It is better to test HHVM for few days and then take your decision.Having it installed on your system will help you going back to your configuration easily.

Handling 504 Errors

You might have 504 issues.I ran into these problems after sometime.This is execution time out issue.So you need to make changes into your hhvm.conf file.This file is located into /etc/nginx directory.You can copy below code into this file.Note the file will have lines into it.So you can take backup of it and create a fresh hhvm.conf file.In that file add below lines

location ~ .(hh|php)$ {
    fastcgi_keep_conn on;
    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include        fastcgi_params;
    fastcgi_read_timeout 300;
    try_files $uri =404;
    limit_conn phplimit 5;
    fastcgi_split_path_info ^(.+.php)(/.+)$;

Some of the above lines are included in hhvm.conf file.I have added below lines into the file

    fastcgi_read_timeout 300;
    try_files $uri =404;
    limit_conn phplimit 5;
    fastcgi_split_path_info ^(.+.php)(/.+)$;

HHVM Configuration files

If you have installed HHVM using above process then it would create below configuration files in directory /etc/hhvm

  • server.ini
  • php.ini

In case you want HipHop Virtual Machine to listen on separate post then 9000 then you need to edit server.ini file.You will have below entry in server.ini file

hhvm.server.port = 9000

You can change 9000 to any post of your choice and then restart the HipHop Virtual Machine using below command

service hhvm restart

After changing port in this file you need to change hhvm.conf file inside /etc/nginx.Remember this file is created while configuring your web server for HHVM.You need to change the line shown below.Just change the port 9000 to the one you used in server.ini file.


It also creates below log files in directory /var/log/hhvm

  • error.log
  • access.log

You can view these log files to get an idea of any HHVM errors.

HHVM over Unix Socket

By default HHVM listens on port 9000.As with PHP5-FPM HHVM also performs better if listens to unix socket.So we will make some changes in HipHop Virtual Machine configuration files mentioned above to make it listen on socket.For this open server.ini file located in /etc/hhvm directory.

;hhvm.server.port = 9000

Note in above code we have commented the line hhvm.server.port.We have inserted the line hhvm.server.file_socket=/var/run/hhvm/hhvm.sock.You do not need to create the file hhvm.sock in that directory.It will automatically get created.

Now we need to modify hhvm.conf file located in /etc/nginx directory.You need to make the changes as shown below

#    fastcgi_pass;
fastcgi_pass unix:/var/run/hhvm/hhvm.sock;

We have commented the line fastcgi_pass listening to 9000 and inserted the second line.This will tell Nginx that HHVM is listening to hhvm.sock not 9000.After making these changes you need to restart HHVM and Nginx.Enter below commands

service hhvm restart
service nginx restart

These commands will restart HHVM server and Nginx server.Your changes will immediately be in effect.

Enhancing HHVM PHP.INI file

I was experiencing a weird problem with hhvm-fastcgi.My site was getting 502 issues after few hours.Since my Nginx configuration was well tested it was not Nginx issue.I checked log files of hhvm-fastcgi.The problem was unresponsive scripts.

Due to unresponsive scripts it was throwing FATAL Error.Since Nginx was getting any response from fastcgi it was throwing 502 error.I got this problem for couple of scripts.One time it was with Disqus and other time it was with a script used to get social media count.Below is the message in error.log file located in /var/log/hhvm

Fatal error: entire web request took longer than 30 seconds and timed out in /usr/share/nginx/html/wp-content/plugins/disqus-comment-system/lib/api/disqus/url.php on line 85
Fatal error: entire web request took longer than 30 seconds and timed out in /usr/share/nginx/html/wp-content/plugins/disqus-comment-system/lib/api/disqus/url.php on line 85

These two were working fine with PHP5-FASTCGI.So I thought of adding some of PHP5-FASTCGI parameters to HHVM php.ini file.By default HHVM php.ini file does not contain much configuration parameters.I wanted to tweak some basic parameter to avoid above issue..

max_execution_time = 300
max_input_time = 60
memory_limit = 128M
post_max_size = 12M
upload_max_filesize = 12M

max_execution_time increases time for which a script will be executed.By default it is 30secs so I made it to 300secs.max_input_time is also parameter to control running time of the script.PHP.INI files provide brief details about each of the option.So I am not covering the options in detail here.memory_limit is the amount of memory available to it.

The rest two variables post_max_size and upload_max_filesize control file upload to your website.SO in above case you can upload 12 MB file to your server.I set this to high value as often I need to upload big files to my server using WordPress upload.

So you can safely use above parameters to your php.ini file.So can modify the values as per your requirement.


You can try HipHop Virtual Machine on your website.I have not conducted any tests to check the performance gain.HipHop Virtual Machine team has conducted so many test that it is not worth a effort.Website performance tuning is combination of so many factors that taking care of any one is not going to make any difference.

HHVM will only speed up PHP part of your website.You need to take care of other parts as well.I have taken care of other parts using ngx_pagespeed.The best part is you can run HipHop Virtual Machine on 512 MB VPS server also.This website is running on 512MB VPS only.

Keeping everything same I felt that HHVM does made it faster.Have you used HHVM on your server or planning to do so? If yes then share your thoughts.

Consider sharing this post in case you found this useful.

11 comments HHVM Nginx WordPress a working tutorial

  1. For most sites PHP does the trick if properly configured and used with cache.However HHVM can be tried if you want blazing fast website

Leave a Reply

Your email address will not be published. Required fields are marked *