Merge pull request #60 from clue/nginx

Documentation for nginx

docs/best-practices/deployment.md

@@ -35,6 +35,71 @@ $ curl http://localhost:8080/
 Hello wörld!
 ```
 
+### nginx
+
+nginx is a high performance web server, load balancer and reverse proxy. In
+particular, its high performance and versatility makes it one of the most
+popular web servers. It is used everywhere from the smallest projects to the
+biggest enterprises.
+
+X supports nginx out of the box. If you've used nginx before to run any PHP
+application, using nginx with X is as simple as dropping the project files in
+the right directory. Accordingly, this guide assumes you want to process a
+number of [dynamic routes](../api/app.md#routing) through X and optionally
+include some public assets (such as style sheets and images).
+
+> ℹ️ **PHP-FPM or reverse proxy?**
+> 
+> This section assumes you want to use nginx with PHP-FPM which is a very common,
+> traditional web stack. If you want to get the most out of X, you may also
+> want to look into using the built-in web server with an
+> [nginx reverse proxy](#nginx-reverse-proxy).
+
+Assuming you've followed the [quickstart guide](../getting-started/quickstart.md),
+all you need to do is to point the nginx' [`root`](http://nginx.org/en/docs/http/ngx_http_core_module.html#root)
+("docroot") to the `public/` directory of your project. On top of this, you'll need
+to instruct nginx to process any dynamic requests through X. This can be
+achieved by using an nginx configuration with the following contents:
+
+```
+server {
+    root /home/alice/projects/acme/public;
+    index index.php index.html;
+
+    location / {
+        try_files $uri $uri/ /index.php$is_args$args;
+    }
+
+    location ~ \.php$ {
+        fastcgi_pass localhost:9000;
+        fastcgi_split_path_info ^(.+\.php)(/.+)$;
+        include fastcgi_params;
+        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
+    }
+}
+```
+
+> ℹ️ **New to nginx?**
+>
+> A complete nginx configuration is out of scope for this guide, so we assume
+> you already have nginx and PHP with PHP-FPM up and running. In this example,
+> we're assuming PHP-FPM is already up and running and listens on `localhost:9000`,
+> consult your search engine of choice for basic install instructions. Once this
+> is set up, the above guide should be everything you need to then use X.
+>
+> We recommend using the above nginx configuration as a starting point if you're
+> unsure. In this basic form, it instructs nginx to rewrite any requests for
+> files that do not exist to your `public/index.php` which then processes any
+> requests by checking your [registered routes](../api/app.md#routing).
+
+Once done, you can check your web application responds as expected. Use your
+favorite web browser or command-line tool:
+
+```bash
+$ curl http://localhost/
+Hello wörld!
+```
+
 ### Apache
 
 The Apache HTTP server (httpd) is one of the most popular web servers. In
@@ -143,8 +208,9 @@ combination through the `X_LISTEN` environment variable like this:
 $ X_LISTEN=127.0.0.1:8081 php public/index.php
 ```
 
-While not usually recommended, you can also expose this to the public by using
-the special `0.0.0.0` IPv4 address or `[::]` IPv6 address like this:
+While not usually recommended (see [nginx reverse proxy](#nginx-reverse-proxy)),
+you can also expose this to the public by using the special `0.0.0.0` IPv4 address
+or `[::]` IPv6 address like this:
 
 ```bash
 $ X_LISTEN=0.0.0.0:8080 php public/index.php
@@ -167,7 +233,7 @@ few lines of configuration, which makes it super easy to run X in production.
 > monitoring, depending on your particular needs. Among these is `systemd`, which
 > is very wide-spread on Linux-based systems and in fact comes preinstalled with
 > many of the large distributions. But we love choice. If you prefer different
-> tools, you can adjust the following instructions to suite your needs.
+> tools, you can adjust the following instructions to suit your needs.
 
 First, start by creating a systemd unit file for our application. We can simply
 drop the following configuration template into the systemd configuration
@@ -193,7 +259,7 @@ In this example, we're assuming the system user `alice` has followed the
 [quickstart example](../getting-started/quickstart.md) and has successfully
 installed everything in the `/home/alice/projects/acme` directory. Make sure to
 adjust the system user and paths to your application directory and PHP binary
-to suite your needs.
+to suit your needs.
 
 Once the new systemd unit file has been put in place, we need to activate the
 service unit once like this:
@@ -224,16 +290,63 @@ This should be enough to get you started with systemd. If you want to learn more
 about systemd, check out the
 [official documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html).
 
+### nginx reverse proxy
+
+If you're using the built-in web server, X will listen on `http://127.0.0.1:8080`
+[by default](#listen-address). Instead of using the `X_LISTEN` environment to
+change to a publicly accessible listen address, it's usually recommended to use
+a reverse proxy instead for production deployments.
+
+By using nginx as a reverse proxy, we can leverage a high performance web server
+to handle static assets (such as style sheets and images) and proxy any
+requests to [dynamic routes](../api/app.md#routing) through X. On top of this,
+we can configure nginx to log requests, handle rate limits, and to provide HTTPS
+support (TLS/SSL termination).
+
+Assuming you've followed the [quickstart guide](../getting-started/quickstart.md),
+all you need to do is to point the nginx' [`root`](http://nginx.org/en/docs/http/ngx_http_core_module.html#root)
+("docroot") to the `public/` directory of your project. On top of this, you'll need
+to instruct nginx to process any dynamic requests through X. This can be
+achieved by using an nginx configuration with the following contents:
+
+```
+server {
+    root /home/alice/projects/acme/public;
+    index index.php index.html;
+
+    location / {
+        try_files $uri $uri/ @x;
+    }
+
+    location @x {
+        proxy_pass http://localhost:8080;
+    }
+}
+```
+
+> ℹ️ **New to nginx?**
+>
+> A complete nginx configuration is out of scope for this guide, so we assume
+> you already have nginx up and running. Unlike [using nginx with PHP-FPM](#nginx),
+> this example does not require a PHP-FPM setup.
+>
+> We recommend using the above nginx configuration as a starting point if you're
+> unsure. In this basic form, it instructs nginx to rewrite any requests for
+> files that do not exist to your `public/index.php` which then processes any
+> requests by checking your [registered routes](../api/app.md#routing).
+
+Once done, you can check your web application responds as expected. Use your
+favorite web browser or command-line tool:
+
+```bash
+$ curl http://localhost/
+Hello wörld!
+```
+
 ### Docker containers
 
 > ⚠️ **Documentation still under construction**
 >
 > You're seeing an early draft of the documentation that is still in the works.
 > Give feedback to help us prioritize.
 > We also welcome [contributors](../more/community.md) to help out!
-
-### More
-
-If you're going to use this in production, we still recommend running this
-behind a reverse proxy such as nginx, HAproxy, etc. for TLS termination
-(HTTPS support).