Skip to content

Commit 62e9f9f

Browse files
SimonFringsSimonFrings
authored
Merge pull request #60 from clue/nginx
Documentation for nginx
2 parents f07db16 + 147c9e5 commit 62e9f9f

1 file changed

Lines changed: 123 additions & 10 deletions

File tree

‎docs/best-practices/deployment.md‎

Lines changed: 123 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,71 @@ $ curl http://localhost:8080/
3535
Hello wörld!
3636
```
3737

38+
### nginx
39+
40+
nginx is a high performance web server, load balancer and reverse proxy. In
41+
particular, its high performance and versatility makes it one of the most
42+
popular web servers. It is used everywhere from the smallest projects to the
43+
biggest enterprises.
44+
45+
X supports nginx out of the box. If you've used nginx before to run any PHP
46+
application, using nginx with X is as simple as dropping the project files in
47+
the right directory. Accordingly, this guide assumes you want to process a
48+
number of [dynamic routes](../api/app.md#routing) through X and optionally
49+
include some public assets (such as style sheets and images).
50+
51+
> ℹ️ **PHP-FPM or reverse proxy?**
52+
>
53+
> This section assumes you want to use nginx with PHP-FPM which is a very common,
54+
> traditional web stack. If you want to get the most out of X, you may also
55+
> want to look into using the built-in web server with an
56+
> [nginx reverse proxy](#nginx-reverse-proxy).
57+
58+
Assuming you've followed the [quickstart guide](../getting-started/quickstart.md),
59+
all you need to do is to point the nginx' [`root`](http://nginx.org/en/docs/http/ngx_http_core_module.html#root)
60+
("docroot") to the `public/` directory of your project. On top of this, you'll need
61+
to instruct nginx to process any dynamic requests through X. This can be
62+
achieved by using an nginx configuration with the following contents:
63+
64+
```
65+
server {
66+
root /home/alice/projects/acme/public;
67+
index index.php index.html;
68+
69+
location / {
70+
try_files $uri $uri/ /index.php$is_args$args;
71+
}
72+
73+
location ~ \.php$ {
74+
fastcgi_pass localhost:9000;
75+
fastcgi_split_path_info ^(.+\.php)(/.+)$;
76+
include fastcgi_params;
77+
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
78+
}
79+
}
80+
```
81+
82+
> ℹ️ **New to nginx?**
83+
>
84+
> A complete nginx configuration is out of scope for this guide, so we assume
85+
> you already have nginx and PHP with PHP-FPM up and running. In this example,
86+
> we're assuming PHP-FPM is already up and running and listens on `localhost:9000`,
87+
> consult your search engine of choice for basic install instructions. Once this
88+
> is set up, the above guide should be everything you need to then use X.
89+
>
90+
> We recommend using the above nginx configuration as a starting point if you're
91+
> unsure. In this basic form, it instructs nginx to rewrite any requests for
92+
> files that do not exist to your `public/index.php` which then processes any
93+
> requests by checking your [registered routes](../api/app.md#routing).
94+
95+
Once done, you can check your web application responds as expected. Use your
96+
favorite web browser or command-line tool:
97+
98+
```bash
99+
$ curl http://localhost/
100+
Hello wörld!
101+
```
102+
38103
### Apache
39104

40105
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:
143208
$ X_LISTEN=127.0.0.1:8081 php public/index.php
144209
```
145210

146-
While not usually recommended, you can also expose this to the public by using
147-
the special `0.0.0.0` IPv4 address or `[::]` IPv6 address like this:
211+
While not usually recommended (see [nginx reverse proxy](#nginx-reverse-proxy)),
212+
you can also expose this to the public by using the special `0.0.0.0` IPv4 address
213+
or `[::]` IPv6 address like this:
148214

149215
```bash
150216
$ 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.
167233
> monitoring, depending on your particular needs. Among these is `systemd`, which
168234
> is very wide-spread on Linux-based systems and in fact comes preinstalled with
169235
> many of the large distributions. But we love choice. If you prefer different
170-
> tools, you can adjust the following instructions to suite your needs.
236+
> tools, you can adjust the following instructions to suit your needs.
171237
172238
First, start by creating a systemd unit file for our application. We can simply
173239
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
193259
[quickstart example](../getting-started/quickstart.md) and has successfully
194260
installed everything in the `/home/alice/projects/acme` directory. Make sure to
195261
adjust the system user and paths to your application directory and PHP binary
196-
to suite your needs.
262+
to suit your needs.
197263

198264
Once the new systemd unit file has been put in place, we need to activate the
199265
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
224290
about systemd, check out the
225291
[official documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html).
226292

293+
### nginx reverse proxy
294+
295+
If you're using the built-in web server, X will listen on `http://127.0.0.1:8080`
296+
[by default](#listen-address). Instead of using the `X_LISTEN` environment to
297+
change to a publicly accessible listen address, it's usually recommended to use
298+
a reverse proxy instead for production deployments.
299+
300+
By using nginx as a reverse proxy, we can leverage a high performance web server
301+
to handle static assets (such as style sheets and images) and proxy any
302+
requests to [dynamic routes](../api/app.md#routing) through X. On top of this,
303+
we can configure nginx to log requests, handle rate limits, and to provide HTTPS
304+
support (TLS/SSL termination).
305+
306+
Assuming you've followed the [quickstart guide](../getting-started/quickstart.md),
307+
all you need to do is to point the nginx' [`root`](http://nginx.org/en/docs/http/ngx_http_core_module.html#root)
308+
("docroot") to the `public/` directory of your project. On top of this, you'll need
309+
to instruct nginx to process any dynamic requests through X. This can be
310+
achieved by using an nginx configuration with the following contents:
311+
312+
```
313+
server {
314+
root /home/alice/projects/acme/public;
315+
index index.php index.html;
316+
317+
location / {
318+
try_files $uri $uri/ @x;
319+
}
320+
321+
location @x {
322+
proxy_pass http://localhost:8080;
323+
}
324+
}
325+
```
326+
327+
> ℹ️ **New to nginx?**
328+
>
329+
> A complete nginx configuration is out of scope for this guide, so we assume
330+
> you already have nginx up and running. Unlike [using nginx with PHP-FPM](#nginx),
331+
> this example does not require a PHP-FPM setup.
332+
>
333+
> We recommend using the above nginx configuration as a starting point if you're
334+
> unsure. In this basic form, it instructs nginx to rewrite any requests for
335+
> files that do not exist to your `public/index.php` which then processes any
336+
> requests by checking your [registered routes](../api/app.md#routing).
337+
338+
Once done, you can check your web application responds as expected. Use your
339+
favorite web browser or command-line tool:
340+
341+
```bash
342+
$ curl http://localhost/
343+
Hello wörld!
344+
```
345+
227346
### Docker containers
228347

229348
> ⚠️ **Documentation still under construction**
230349
>
231350
> You're seeing an early draft of the documentation that is still in the works.
232351
> Give feedback to help us prioritize.
233352
> We also welcome [contributors](../more/community.md) to help out!
234-
235-
### More
236-
237-
If you're going to use this in production, we still recommend running this
238-
behind a reverse proxy such as nginx, HAproxy, etc. for TLS termination
239-
(HTTPS support).

0 commit comments

Comments
 (0)