<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<sect1 xml:id="install.unix.nginx" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Nginx 1.4.x on Unix systems</title>

 <para>
  This documentation will cover installing and configuring PHP with
  PHP-FPM for a Nginx 1.4.x HTTP server.
 </para>

 <para>
  This guide will assume that you have built Nginx from source and therefore
  all binaries and configuration files are located at
  <literal>/usr/local/nginx</literal>. If this is not the case and you have
  obtained Nginx through other means then please refer to the
  <link xlink:href="&url.nginx;">Nginx Wiki</link> in order to translate
  this manual to your setup.
 </para>

 <para>
  This guide will cover the basics of configuring an Nginx server to
  process PHP applications and serve them on port 80, it is recommended
  that you study the Nginx and PHP-FPM documentation if you wish to
  optimise your setup past the scope of this documentation.
 </para>

 <para>
  Please note that throughout this documentation version numbers have been
  replaced with an 'x' to ensure this documentation stays correct in the future,
  please replace these as necessary with the corresponding version numbers.
 </para>

 <orderedlist>
  <listitem>
   <para>
    It is recommended that you visit the Nginx Wiki
    <link xlink:href="&url.nginx.wiki.install;">install</link> page 
    in order to obtain and install Nginx on your system.
   </para>
  </listitem>

  <listitem>
   <para>
    Obtain and unpack the PHP source:
   </para>

   <informalexample xml:id="install.unix.nginx.extract.php">
    <screen>
<![CDATA[
tar zxf php-x.x.x
]]>
    </screen>
   </informalexample>
  </listitem>

  <listitem>
   <para>
    Configure and build PHP.  This is where you customize PHP
    with various options, like which extensions will be enabled. Run
    ./configure --help for a list of available options.  In our example
    we'll do a simple configure with PHP-FPM and MySQLi support.
   </para>

   <informalexample xml:id="install.unix.nginx.build.php">
    <screen>
<![CDATA[
cd ../php-x.x.x
./configure --enable-fpm --with-mysqli
make
sudo make install
]]>
    </screen>
   </informalexample>
  </listitem>

  <listitem>
   <para>
    Obtain and move configuration files to their correct locations
   </para>

   <informalexample xml:id="install.unix.nginx.configure.php">
    <screen>
<![CDATA[
cp php.ini-development /usr/local/php/php.ini
cp /usr/local/etc/php-fpm.d/www.conf.default /usr/local/etc/php-fpm.d/www.conf
cp sapi/fpm/php-fpm /usr/local/bin
]]>
    </screen>
   </informalexample>
  </listitem>

  <listitem>
   <para>
    It is important that we prevent Nginx from passing requests to the
    PHP-FPM backend if the file does not exist, allowing us to prevent
    arbitrarily script injection.
   </para>
   <para>
    We can fix this by setting the
    <link linkend="ini.cgi.fix-pathinfo">cgi.fix_pathinfo</link>
    directive to <literal>0</literal> within our php.ini file.
   </para>
   <para>
    Load up php.ini:
   </para>

   <informalexample xml:id="install.unix.nginx.configure.ini">
    <screen>
<![CDATA[
vim /usr/local/php/php.ini
]]>
    </screen>
   </informalexample>

   <para>
    Locate <literal>cgi.fix_pathinfo=</literal> and modify it as follows:
   </para>

   <informalexample xml:id="install.unix.nginx.configure.pathinfo">
    <screen>
<![CDATA[
cgi.fix_pathinfo=0
]]>
    </screen>
   </informalexample>
  </listitem>

  <listitem>
   <para>
    php-fpm.conf must be modified to specify that php-fpm must run as the user
    www-data and the group www-data before we can start the service:
   </para>

   <informalexample xml:id="install.unix.nginx.modify.phpfpm">
    <screen>
<![CDATA[
vim /usr/local/etc/php-fpm.d/www.conf
]]>
    </screen>
   </informalexample>

   <para>
    Find and modify the following: 
   </para>

   <informalexample xml:id="install.unix.nginx.modify.phpfpm.usergroup">
    <screen>
<![CDATA[
; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
;       will be used.
user = www-data
group = www-data
]]>
    </screen>
   </informalexample>

   <para>
    The php-fpm service can now be started:
   </para>

   <informalexample xml:id="install.unix.nginx.start.phpfpm">
    <screen>
<![CDATA[
/usr/local/bin/php-fpm
]]>
    </screen>
   </informalexample>

   <para>
    This guide will not configure php-fpm any further, if you are interested
    in further configuring php-fpm then please consult the documentation.
   </para>
  </listitem>

  <listitem>
   <para>
    Nginx must now be configured to support the processing of PHP applications:
   </para>

   <informalexample xml:id="install.unix.nginx.configure.nginx">
    <programlisting>
<![CDATA[
vim /usr/local/nginx/conf/nginx.conf
]]>
    </programlisting>
   </informalexample>

   <para>
    Modify the default location block to be aware it must attempt
    to serve .php files:
   </para>

   <informalexample xml:id="install.unix.nginx.configure.nginx.location">
    <programlisting role="nginx-conf">
<![CDATA[
location / {
    root   html;
    index  index.php index.html index.htm;
}
]]>
    </programlisting>
   </informalexample>

   <para>
    The next step is to ensure that .php files are passed to the
    PHP-FPM backend. Below the commented default PHP location block,
    enter the following:
   </para>

   <informalexample xml:id="install.unix.nginx.configure.nginx.php">
    <programlisting role="nginx-conf">
<![CDATA[
location ~* \.php$ {
    fastcgi_index   index.php;
    fastcgi_pass    127.0.0.1:9000;
    include         fastcgi_params;
    fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
    fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
}
]]>
    </programlisting>
   </informalexample>

   <para>
    Restart Nginx.
   </para>

   <informalexample xml:id="install.unix.nginx.restart.nginx">
    <screen>
<![CDATA[
sudo /usr/local/nginx/sbin/nginx -s stop
sudo /usr/local/nginx/sbin/nginx
]]>
    </screen>
   </informalexample>
  </listitem>

  <listitem>
   <para>
    Create a test file
   </para>

   <informalexample xml:id="install.unix.nginx.test.nginx.php">
    <screen>
<![CDATA[
rm /usr/local/nginx/html/index.html
echo "<?php phpinfo(); ?>" >> /usr/local/nginx/html/index.php
]]>
    </screen>
   </informalexample>

   <para>
    Now navigate to http://localhost. The phpinfo() should now be shown.
   </para>
  </listitem>
 </orderedlist>

 <para>
  Following the steps above you will have a running Nginx web server with
  support for PHP as an <literal>FPM</literal> <literal>SAPI</literal> module.  Of course there are
  many more configuration options available for Nginx and PHP.  For more
  information type <command>./configure --help</command> in the corresponding
  source tree.
 </para>

</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->