How-to
Website
Web app
Serve a site with nginx
This recipe serves a WebFluent build from a server of your own with nginx: the precompressed files the build wrote, its 404 page, and the cache and security headers. You need a server running nginx with a TLS certificate for the site, and a build/ folder from wf build (Install wf on a build machine). Put the security headers in a file of their own, so every block that needs them can include them:
# /etc/nginx/snippets/site-headers.conf
add_header X-Content-Type-Options nosniff always;
add_header Referrer-Policy strict-origin-when-cross-origin always;
add_header X-Frame-Options DENY always;
# add_header Content-Security-Policy "…as in build/_headers…" always;
Then add this server block, and pick the try_files line for your kind of build:
server {
listen 443 ssl http2;
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
root /var/www/site;
gzip_static on; # serve the .gz files the build wrote
include snippets/site-headers.conf;
location / {
try_files $uri $uri/ $uri.html =404; # a static build
# try_files $uri $uri/ /index.html; # a single-page build
}
error_page 404 /404.html;
location = /sw.js {
include snippets/site-headers.conf;
add_header Cache-Control "no-cache";
}
# Pictures the build resized and renamed: hero.4a6178a1.960.webp, hero.4a6178a1.jpg
location ~* "\.[0-9a-f]{8}(\.[0-9]+)?\.(webp|avif|jpe?g|png|gif)$" {
include snippets/site-headers.conf;
add_header Cache-Control "public, max-age=31536000, immutable";
}
}
Upload the build with any tool — for example, rsync — and reload nginx:
$ rsync -a --delete build/ server:/var/www/site/
How it works
rootis the folder the build is uploaded to.gzip_static onsends the.gzfile the build wrote beside a text file when the browser accepts gzip, so nginx compresses nothing itself.try_filesdecides what a path reaches. In a static build,/contactiscontact/index.html($uri/) or, withclean_urls: "file",contact.html($uri.html); anything else is a 404. In a single-page build, every path falls back toindex.html, where the router draws the page.error_page 404 /404.htmlserves the page whosepathis*.sw.jsis never cached without asking. The pictures the build resized and renamed (img/hero.<hash>.<width>.webp, and the original asimg/hero.<hash>.jpg) are cached for a year, since a changed picture gets a new name. A file ofpublic/keeps the name you gave it, so it is left to the browser's usual checks: a new/logo.pngreaches readers at once (Set cache headers).- The
add_headerlines are the security headers the build writes tobuild/_headers. Copy theContent-Security-Policyline from that file into the commented line to send the policy as a header too. - nginx drops the server's
add_headerlines in anylocationthat has anadd_headerof its own. That is why the two locations that setCache-Controlinclude the headers file again: without it,sw.jsand the pictures would be sent with no security headers. ssl_certificateandssl_certificate_keyname the certificate thelisten 443 sslline needs; the paths above are where Certbot puts them.
rsync -a --delete makes the server's folder match build/, removing files an older build left behind.
Check it
curl -I a page and check the headers. Ask for a compressed copy and check that nginx sends the build's .gz file:
$ curl -sI -H "Accept-Encoding: gzip" https://example.com/app.js
The response has Content-Encoding: gzip. Then go through Check a deploy.