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.
Thank you. Good to know it helped.
Thanks — tell us what was missing. Open a ticket from Support in the console, and we answer on the ticket. Open the console