bfren/nginx repository overview

⁠Nginx

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

A small, sensible nginx⁠ image for serving static files, or as the base for images that need a web server - Nginx + PHP⁠, WordPress⁠, Baikal⁠, FreshRSS⁠ and Nginx + WebDAV⁠ are all built on it.

It is Alpine + S6⁠ with:

• nginx from Alpine's own packages, with the Brotli module (and zstd, on Alpine 3.20 and above)
• a ready-made configuration with zstd, Brotli and gzip compression, hidden version number and sensible defaults
• helper files you can include for static files, error pages, uploads and more
• log forwarding to docker logs, a daily configuration reload and a health check

There is no SSL support - it is designed to run behind a reverse proxy such as Caddy⁠.

⁠Quickstart

Serve the files in ./site on port 8080:

docker run -d --name web -p 8080:80 -v ./site:/www/public bfren/nginx

Or with Docker Compose:

services:
  web:
    image: quay.io/bfren/nginx:nginx1.30-alpine3.24-7.3
    ports:
      - "8080:80"
    volumes:
      - ./site:/www/public

Open http://localhost:8080. If you don't mount anything, nginx serves a "Welcome to Nginx" page.

⁠Features

• 🪶 Alpine 3.15 to 3.24, each with its own nginx version - choose with the image tag
• 🗜️ zstd (Alpine 3.20 and above), Brotli and gzip compression, with pre-compressed .gz and .br files served as they are
• 🔒 server_tokens off, and nginx workers run as a non-root www user
• 🧩 Include-based configuration: add your own sites, server snippets, modules and http settings without replacing nginx.conf
• 📜 Error log always forwarded to docker logs, access log optionally
• 🔁 Configuration tested at start-up, and reloaded every day at 02:00
• 🩺 Health check that loads a URI of your choice (set BF_NGINX_HEALTHCHECK_URI)
• 🧪 Built-in test runner (from Alpine⁠)

⁠Tags

Images are published to Docker Hub (bfren/nginx) and Quay.io (quay.io/bfren/nginx) for linux/amd64, linux/arm/v7 and linux/arm64. Tags include the nginx version, because the version depends on the Alpine release.

Images for unsupported Alpine versions are still built, but no longer receive Alpine security fixes - avoid them for anything new.

⁠Configuration

⁠Ports

⁠Volumes

⁠Environment Variables

Alpine + S6 adds more variables⁠ (timezone, cron).

⁠How It Works

⁠Starting

When the container starts, Alpine + S6⁠ runs the initialisation scripts, then S6 starts three services:

The image's initialisation scripts (10-env, 11-conf, 12-public) set the nginx environment variables, generate the configuration files below from templates, and create the public directory if it doesn't exist.

If the configuration test fails, nginx doesn't start and the container stops - see docker logs for the error.

⁠Configuration files

nginx.conf is generated at start-up from a template, so it picks up your environment variables. You normally don't edit it - add to it using these directories instead:

The default site, sites/localhost.conf, is a single server block that serves /www/public on port 80. Add your own .conf files to sites, or map a file over localhost.conf to replace it.

nginx's own /etc/nginx files are owned by the www user and made read-only at start-up (see ch.d in Alpine + S6⁠), so mounted configuration files must be readable by www.

⁠Helper files

Include these in a server block with include helpers/<name>; (the path is relative to /etc/nginx):

⁠Compression

Text responses are compressed with zstd, Brotli or gzip, depending on what the browser accepts. This happens on the fly for every request - nginx doesn't cache the compressed result. zstd is only installed on Alpine 3.20 and above, because older releases don't have the module; there, responses use Brotli or gzip. Compression levels are 6 for gzip and Brotli, and 3 for zstd. Responses smaller than 256 bytes are not compressed. Only gzip and Brotli have pre-compressed file support (below); zstd is always compressed on the fly.

To avoid that cost for static files, compress them when you build your site: put a .br (brotli -k -q 11 file) and/or a .gz (gzip -k -9 file) next to each file, and nginx serves them directly. brotli_static and gzip_static are both on, and they only take effect when a pre-compressed file exists.

⁠Logs

nginx writes to /var/log/nginx/access.log and error.log. The error log is always forwarded to docker logs. Set BF_NGINX_FORWARD_ACCESS_LOG=1 to forward the access log too - it's off by default so that a busy site doesn't flood the container's log.

⁠Reloading

nginx-reload tests the configuration and, if it is valid, reloads nginx without dropping connections. It does nothing if nginx isn't running. It runs automatically every day at 02:00 (so, for example, renewed certificates or changed files are picked up), and you can run it yourself:

docker exec <container> nginx-reload

⁠Health check

The health check (/etc/bf/health.d/10-nginx.nu) loads BF_NGINX_HEALTHCHECK_URI and passes if the HTTP status is between 200 and 399. Docker runs it every 30 seconds (every 2 seconds during the first 60 seconds, so a new container reports healthy quickly). Use another URI for sites where / isn't a good test - for example, WordPress⁠ uses its login page.

⁠The bf-nginx module

Load it with use bf-nginx. The executable nginx-reload is in /usr/bin/bf and on the PATH.

⁠Building on this image

FROM quay.io/bfren/nginx:nginx1.30-alpine3.24-7.3

COPY ./overlay /
RUN bf-install

Put site configuration in overlay/etc/nginx/sites, extra settings in overlay/etc/nginx/http.d and overlay/etc/nginx/custom, and any installation steps in overlay/tmp/install. Add a script to overlay/etc/bf/health.d to check your own service as well as Nginx, or replace overlay/etc/bf/health.d/10-nginx.nu to change Nginx's check. See Alpine⁠ and Alpine + S6⁠ for everything else.

⁠Testing

./test.nu        # builds the image and runs /test
./test.nu --all  # every version, in parallel

/test runs this image's tests - the configuration check, the generated nginx.conf (compression settings, and zstd only where the module is installed) and nginx-reload - alongside the base images' tests, and fails if tests don't execute. Run it on more than one Alpine version, e.g. ./test.nu 3.19 and ./test.nu 3.24, as zstd is only installed from 3.20.

⁠Troubleshooting

⁠The container stops straight after starting

nginx's configuration test failed. Run docker logs <container> - nginx names the file and line. Common causes are a mounted .conf file that www can't read, or a missing include file.

⁠I get a 404 for everything

nginx serves /www/public, not /www. Mount your files at /www/public, or set BF_NGINX_PUBLIC_OVERRIDE.

⁠Changes to my configuration don't take effect

Run docker exec <container> nginx-reload, or restart the container. nginx.conf, base.conf and ignore-favicon.conf are regenerated from templates every time the container starts, so don't edit them - add to http.d, sites or custom instead.

⁠I can't see access logs in docker logs

Set BF_NGINX_FORWARD_ACCESS_LOG=1. They are always written to /var/log/nginx/access.log inside the container.

⁠The health check fails

The URI in BF_NGINX_HEALTHCHECK_URI must return a 2xx or 3xx status from inside the container. Test it with docker exec <container> bf-healthcheck.

⁠FAQs

⁠Why no SSL?

SSL is better handled once, by a reverse proxy in front of all your containers, than in each one. Caddy⁠ does it automatically.

⁠Can I run PHP?

Use Nginx + PHP⁠, which is built on this image and runs PHP-FPM.

⁠Why do the tags include the nginx version?

nginx comes from Alpine's packages, so each Alpine release has a different version. The tag tells you exactly which you get, and nginxX.Y.Z-alpineA.B-VERSION pins both.

⁠Licence

⁠Copyright