Skip to main content
Open console

Nginx

Serves static files and passes PHP to FPM

5 min read

Every PHP project has Nginx: Drupal, Laravel, WordPress or plain PHP. A Node.js, Go, Python, Ruby or Rust project has it only where its vallic.yaml names it (see In front of an application), and a static site is nginx and nothing else.

Your project type decides what it serves, not a setting:

Project Document root Configuration
Drupal web/ Drupal 11's, or Drupal 10's when runtime.drupal is '10'
Laravel public/ Laravel's
WordPress the repository root WordPress's
PHP public/ a plain PHP one
Node.js, Go, Python, Django, Ruby, Rust public/ files from there, every other path to the application

The code is mounted read-only; uploads are served from the files directory that outlives the release. In front of Nginx is the platform's proxy, which terminates TLS and routes the hostname, or Vinyl Cache (Varnish) when the stack runs it.

Paths under /.well-known/ reach your application, as do /llms.txt, /llms-full.txt, /robots.txt, /humans.txt and /ads.txt. The route your application declares answers them (a discovery document, OpenID's configuration, WebFinger), or a module or plugin that generates them (Drupal's RobotsTxt, WordPress's own robots.txt). A file of that name in the document root is served as a file instead.

A slow request is answered by whichever of Nginx and PHP gives up first. Raise NGINX_FASTCGI_READ_TIMEOUT together with PHP_MAX_EXECUTION_TIME: see Service settings.

In front of an application

A Node.js, Go, Python, Ruby or Rust application is its own server and gets no Nginx unless its repository names one:

services:
  - nginx: '1.31'

Then Nginx answers first:

Request Answered by
A file in the release's public/: compiled assets, images Nginx, from disk
/favicon.ico Nginx, from public/ alone, with an empty image where there is no file
A path under /.well-known/, /llms.txt, /robots.txt, /humans.txt or /ads.txt, or one ending in .mp4, .mov, .m4a or .flv, with no file behind it your application
Every other path your application, on the port it listens on, over HTTP/1.1 with WebSockets passed through

If your application writes /favicon.ico at request time, write it into public/ at its build instead.

Your application sees the scheme and the client's address the platform's proxy saw (X-Forwarded-Proto, X-Forwarded-For) and the hostname that was asked for.

NGINX_CLIENT_MAX_BODY_SIZE is the largest request Nginx passes on: 32 MB unless you raise it. Vinyl Cache, where the stack runs it, asks Nginx rather than the application.

Rules of your own

Two files in your repository add to Nginx's configuration without replacing it, on a PHP project, a static site, or Nginx in front of an application:

File Added to
.vallic/nginx/server.conf the site's server block, after the platform's: a location of your own, a redirect, a header
.vallic/nginx/http.conf the http block, for what Nginx allows only there and a location names: a proxy_cache_path, an upstream, a map, a limit_req_zone

A week's cache of the thumbnails an application makes, and an old address sent on:

# .vallic/nginx/http.conf
proxy_cache_path /var/cache/nginx/thumbnails levels=1:2 keys_zone=thumbnails:10m max_size=1g inactive=7d use_temp_path=off;
# .vallic/nginx/server.conf
location ^~ /thumbnails/ {
    proxy_cache thumbnails;
    proxy_cache_valid 200 7d;
    proxy_cache_use_stale error timeout updating;
    proxy_set_header Host $http_host;
    proxy_pass http://app_server;
}

location = /old-pricing {
    return 301 /pricing;
}

In front of an application, app_server is your application and @app the location that passes a request on to it, the scheme and the client's address included. On a PHP project, php is PHP-FPM. /var/cache/nginx is Nginx's to write, and starts empty when Nginx is restarted.

Your locations come after the platform's:

  • One with = or ^~ answers for its paths ahead of the platform's regular expressions.
  • A regular expression of yours is tried after the platform's, so one of theirs that matches first answers.
  • A location the platform already has, location / among them, is refused by Nginx as a duplicate: name a more specific one.

On a Drupal site, Drupal's installer, /core/install.php, answers 404, and a location of yours for that path is a duplicate. A site is installed with drush site:install in its deploy script, as Drupal shows.

A change takes effect with the deploy that carries it, not when you push. A rollback brings back the rules of the release you roll back to.

Each file is at most 8 KB. A file may not include another file or load a module, and http.conf may not declare a server. server.conf holds locations and directives, not a block around them. A file that does is left out, and Nginx runs without it.

The machine tests your rules with nginx -t before Nginx reads them. Rules Nginx refuses are not loaded: Nginx keeps the rules that last passed. Web server rules on the environment's Resources tab says what Nginx said, with the file and the line.

Where Nginx would start from a new definition, a new version or new settings, that refuses your rules, nothing of the change is made until the rule is fixed.

Versions

Version Status
1.31 Supported, and the default
1.30 Supported

Pin the version, not the build: name 1.31 and the platform matches it to the current build, so a security rebuild reaches you without anybody editing a repository.

What you can change

In vallic.yaml — what each one does is on Service settings:

services:
  - nginx:
      version: '1.31'
      environment:
        NGINX_CLIENT_MAX_BODY_SIZE: …
        NGINX_KEEPALIVE_TIMEOUT: …
        NGINX_FASTCGI_READ_TIMEOUT: …
        NGINX_GZIP_COMP_LEVEL: …
        NGINX_STATIC_EXPIRES: …
        NGINX_ERROR_LOG_LEVEL: …
        NGINX_DRUPAL_NOT_FOUND_REGEX: …
        NGINX_WP_NOT_FOUND_REGEX: …

Anything not on this list refuses the deploy, naming the variable — rather than being accepted and quietly ignored.

Need a hand?

Open a ticket from Support in the console. We answer on the ticket.

Open the console How support works