Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation for nginx #60

Merged
merged 2 commits into from
Nov 22, 2021
Merged

Documentation for nginx #60

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4cf8eb0
Documentation for nginx
clue Nov 21, 2021
147c9e5
Documentation for nginx reverse proxy
clue Nov 21, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 123 additions & 10 deletions docs/best-practices/deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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).