Turning It Up To Eleven!
DreamFactory can be configured to use any web server. The core package ships with configuration examples for Apache as well as nginx. This guide will show you how to transform your ordinary, default Apache/pre-fork DSP into a shiny new nginx/FPM DSP! Sound cool? Read on!
Web Server Selection
You cannot change the web server on a DSP installed with a Bitnami package or running on our Free Hosted Edition. If you want to experience all the joy of the nginx, you'll need to be running a self-installed server.
Assumptions & Prerequisites
This guide assumes you're running the latest DreamFactory Services Platform™ and on a major linux distribution (Ubuntu, CentOS, Red Hat, Debian), or a derivative thereof. The DSP can be a virtual machine on your dev box, a vagrant box, or even an actual, physical server. Other distributions may need tweaking to locations. But the configuration options should be the same. It is also assumed (and required) that you have sudo access to your DSP's server.
If you've already installed the necessary packages, you can skip ahead to the next part.
We need to install two main packages to get this going. The first is the nginx server package. The second is PHP FPM, or FastCGI Process Manager, package. Check out the link if you're not familiar with it.
We are going to install the
nginx-extras package for this guide. It is a package that requires the nginx server as well as a few extras we need:
When that's done you'll have a nice new
/etc/nginx directory to play with.
Install PHP FPM
The second package we need is the PHP FPM package. Install it like this:
After it's installed, we need to copy a file from the DSP to the PHP FPM directory. It's detailed in the Configuration section below.
The VERY first thing you should do is make a copy of the nginx installation. You can do this easily:
That will come in handy someday when you break your server. Trust me. ;)
Now we can start fiddling in the configs. We need to copy a few files from your DSP installation directory.
Your Current Directory
For the purpose of this guide, we will assume you are in your DSP's root directory. All paths shown will be relative from there.
First the PHP FPM file:
Cool beans. Now we copy the nginx files:
What Have I Done?!
The files copied above are building blocks and do not overwrite anything that is owned by nginx. Here's a quick rundown of what they are:
dsp-locations.conf is included by the files in
/etc/nginx/sites-available to configure the web server's routes.
/etc/nginx/sites-available now has two new files:
dsp.multi.local. These both do the same thing in different ways.
What are these files?
These files configure nginx to listen for web connections and send it to PHP. If you're going to use SSL on your site we recommend you use the
dsp.single.local file as your configuration. The single file runs the DSP in a single server section of the nginx configuration. If you're not running SSL, or not yet at least, the multi file has a server configuration for HTTP and HTTPS separated. You can comment out the HTTPS section if you do not want to use SSL.
/etc/nginx/conf.d there are few new files:
dreamfactory.php-fpm.conf. These configure nginx for PHP FPM and set a few defaults. Please read through them if you've not already. They're commented and you can change to your liking. That goes pretty much for all these config files.
In addition, there a new directory called
ssl in which there is a file called
dreamfactory.ssl.conf. If you're going to run SSL you just need to put the location of your keys into that file. If you're not running SSL it is ignored. This is placed in a separate place so it can be made as secure as you require.
SSL Configuration File Location
You can adjust the source of the include from
conf.d/ssl/ to anything you want. We'll cover that in a bit.
The last file we need to copy is the
nginx.conf file. This step is optional. You might not want to copy this file over the default configuration without giving a good perusal.
We have found these settings to be generally good and many thanks to the gentleman referenced in that configuration file for those settings. There aren't any settings in our version of
nginx.conf that are required to run the DSP properly. It is just tuned for speed. (thanks to that dude...).
So copy it if you want:
Choose Your Destructor
If you haven't decided by now if you're going to use the single or multi configuration files outlined above, go with the multi. Either way, you need to create a new configuration for your DSP using one of the two samples. We're going to use the single version and call it
Go on in the new file (
dsp.local) with your favorite editor and change anything that calls out to you. Your DSP root directory perhaps, the server name, port, etc. Make sure you test your changes before restarting nginx by using the following command:
If you messed up, you'll get this fail:
When you're in DGM (deep geek mode), having to type
sudo service nginx restart two or three times a minute gets old. So create an alias to do the typing for you!
I run Ubuntu and bash is the shell that I use. When you log in, or open a terminal window, bash sources your
~/.bash_aliases file. If you don't have one, you can create one and it will automatically be sourced upon next and future logins.
Here are a few of the things in my
~/.bash_aliases file for these types of situations. Feel free to add them to your arsenal.
Enable the DSP Server
The nginx server ships with a default server configuration (in
/etc/nginx/sites-available/default), which is enabled.
If you're not using (going to use) it, you should disable it:
Now we need to enable the DSP, done via symbolic link:
What we're doing is symlinking the
sites-available configuration into the
sites-enabled directory. Now we test the configuration before restarting the service:
If you want to disable the DSP from nginx, just unlink the symbolic link we just created:
Restart the Server
Restart nginx now
Now you can test out your DSP on nginx. Please let us know how your experiences compare using nginx vs. Apache, or any other server for that matter!
I'll be posting an update to this soon with benchmarks between the DSP on Apache vs. nginx. That should be interesting.