There are two ways to install nginx, either by building it from source, or by installing a binary package via a package manager, such as yum or apt. Each method has its own pros and cons, and which method we choose depends on what we need nginx to do and which OS we're using.
Historically nginx, Inc has only provided the source files for nginx so that we could compile the software ourselves, and only recently have they begun distributing binary packages for the various Linux distributions. Additionally, nginx requires that third party modules are compiled statically instead of being loaded at runtime. The end result of this is that the nginx ecosystem ends up with a number of native binary packages and custom binary packages built by different people to include different modules.
Even today many of the Linux distributions ship very old versions of nginx, which means we'll have to be careful when we install nginx to make sure we get the version we need. If we need any third party modules enabled, we are almost guaranteed to have to build from source. Thankfully, nginx is easy to install from source and this book details how to do it without suffering a nervous breakdown.
A last note before we continue to the installation process. nginx has three versions available: development, stable, and legacy. Development here refers to the program API stability, not runtime stability. This means that the development version is usually just as stable, or even more stable than the stable branch. This is because bug fixes are added to the development branch before the stable branch. In general, if I personally want features in a new development version, I will give it a week or two to be tested by the community and then feel safe upgrading to it. Legacy versions should be avoided, as they are not supported by either nginx, Inc or the community, and usually bugs are fixed by simply updating to the stable or development version.
Now, we will have a look at installing nginx on different operating systems.
Installing on Windows is the easiest of them all, as it's really only available as a binary file unless we want to start compiling through Cygwin, for most people this is overkill. Instead, just head to the nginx download page and get one of the Windows releases as signified by nginx/Windows-1.X.XX. Extract that anywhere and we're ready to go!
A word of warning about nginx on Windows though. Windows has a unique version of event polling called IOCP and nginx does not currently support this. This means that nginx falls back to a slower variant, which means that nginx on Windows is not at the same performance standard as nginx on Linux. Additionally, there are a number of limitations that we should be aware of. At the time of writing the following are the known limitations:
Only one worker will be used
A worker can handle no more than 1,024 concurrent connections
Cache modules do not work on Windows Vista or later
nginx, Inc maintains an updated list of known limitations at the following URL:
To install on Linux we first need to decide whether we'll compile from source or install via a binary package. To help decide, here's a brief overview of the pros and cons:
The pros of installing nginx on Linux via source are as follows:
It can easily use third party modules
It can use the latest version immediately
The cons of installing nginx on Linux via source are as follows:
It is more difficult than installing a binary package
You have to keep on top of updates yourself
The pros of installing nginx on Linux via binary package are as follows:
It is very easy to install
You don't have to keep track of updates yourself
The cons of installing nginx on Linux via binary package are as follows:
It is difficult to find a binary package with third party modules
It is potentially lagging behind on versions
It has many different versions, need to research them
Ultimately I personally think it comes down to whether or not you need third party modules. Finding binary packages that contain the modules you need is often difficult and you rely on external people to keep their binary package updated. Compiling from source if you need third party modules also means that we can restrict binary packages to the official nginx provided repositories. This makes it far easier and reduces the research required into the various custom repositories and Ubuntu Personal Package Archives (PPAs).
Installing nginx from source is not as daunting as it might sound, as nginx is a fairly simple piece of software and we can still utilize yum and apt-get to simplify the installation of the dependencies.
If using apt, simply run the following:
sudo apt-get build-dep nginx
To automatically install the dependencies for their nginx package, usually these are the same as for what we will install.
If using yum, run the following:
sudo yum install pcre-devel zlib-devel openssl-devel
At this point we have the dependencies and are ready to compile nginx. Make sure we're in the directory we want to download the source code into and then run the following:
wget http://www.nginx.org/download/nginx-1.3.15.tar.gz tar zxf nginx-1.3.15.tar.gz cd nginx-1.3.15 ./configure --help
After running the last command we should get a large amount of text on the screen. If you're not used to compiling from source, this would probably be pretty daunting at first, but let's read through the important points.
--prefix
|
This sets the base path where nginx is installed. If not defined, this will default to |
--sbin-path
|
This sets the path where the binary file is installed. |
--conf-path
|
This sets the path of the configuration file. |
Any of the other install specific switches can be configured in the configuration file, so those really aren't important to set yet. Further down we start seeing switches named as —with-* and —without-*. Each of these allow us to define which standard modules go into our compiled binary package, and the switches we use depend on which features we want. Each module we include increases the size of the binary package, which increases memory usage. Although, even if we include all the modules, the memory size won't be more than a few megabytes. Do note that some modules might have other dependencies, for instance the GeoIP module relies on external GeoIP software which will have to be installed through your package manager. To read about what each module does, please refer to the official documentation at: http://www.nginx.org/en/docs/.
Once we have decided the modules we want to be included, simply run the following:
./configure —with-foo
If all the dependencies are correct, a summary screen should be presented as follows:
If the information there is as expected, complete the compile by running the follow commands:
make make install
If we already have nginx installed, we can have the make script automatically and seamlessly rotate the running binary package by using the following command:
make upgrade
If we did everything right, we should get the following message after running make install:
make[1]: Leaving directory '/path/to/nginx-1.3.15'
The quickest way to install from a binary package is to simply use the native packages and run either of the following:
yum install nginx
or
apt-get install nginx
If the version installed is fairly recent, we might want to do just that for convenience, if it's old then move on and use the nginx provided binary packages. To use these first install the repository like so.
For yum:
Create the file /etc/yum.repos.d/nginx.repo and add the following to it:
[nginx] name=nginx repo baseurl=http://nginx.org/packages/OS/OSRELEASE/$basearch/ gpgcheck=0 enabled=1
Where OS is centos if CentOS is used and rhel if RHEL, or another RHEL-based distribution is used. OSRELEASE is the OS version number, being either 5 or 6. If unsure check uname -a for a clue, or use the tried and tested method of trial and error.
For apt:
Add the following to /etc/apt/sources.list for Debian:
deb http://nginx.org/packages/debian/ squeezenginx deb-src http://nginx.org/packages/debian/ squeezenginx
For Ubuntu, add the following:
deb http://nginx.org/packages/ubuntu/ codenamenginx deb-src http://nginx.org/packages/ubuntu/ codenamenginx
Where codename is one of lucid, oneiric, precise, or quantal, depending on which version is used and then run:
apt-get update apt-get install nginx
Regardless of how nginx was installed, we will most likely want to start it by using a script. Our options are the classic init.d script or an upstart/systemd script depending on our platform. If nginx was installed via a binary package, one such script should already have been provided for us and can be used by running:
service nginx start
If nginx was installed via source, we'll need to install the init script ourselves. An nginx community effort to gather .init scripts can be found at: http://wiki.nginx.org/InitScripts, which will help us get set up quickly.
Download the init script for the relevant platform and save it to /etc/rc.d/init.d/nginx, check the paths in the .init file to make sure they fit the install configurations we set with the ./configure arguments (or the defaults!), and then run the following:
chmod +x /etc/rc.d/init.d/nginx
Now run the preceding command up above to see the options available.