australproject/nginx repository overview

⁠Austral Docker Nginx

View repository for the base image Alpine 3.23 : Docker Hub⁠ or Gitub⁠

⁠Versions

• Alpine: 3.23
• Nginx: 1.28
• Brotli module: installed when available (enabled automatically)

⁠Modes

With MODE=php, PHP_MODE defines which PHP files can be executed:

Allowed scripts (PHP_MODE=front): some projects have extra scripts reachable by URL, for example a yipikai.php that switches the site to dev mode. List them explicitly:

environment:
  - PHP_MODE=front
  - PHP_ALLOWED_SCRIPTS=yipikai.php            # comma separated, file names at the root of the public directory
  - PHP_ALLOWED_SCRIPTS_IPS=203.0.113.10,198.51.100.0/24   # optional: only these IPs can reach them

The front controller itself (PHP_FRONT_SCRIPT, default index.php) is never reachable directly, only through the application routes. With PHP_ALLOWED_SCRIPTS_IPS, other visitors get a 403 (the real client IP is used, see REAL_IP_FROM).

Previous settings still work: ALONE=true or FASTCGI_PASS=alone select MODE=static, FASTCGI_PASS_VALUE is used as FASTCGI_PASS, and a mounted /etc/nginx/sites-available/website.custom still replaces the site configuration.

⁠Running as any user (non-root)

The image runs as root or as any UID/GID, for example with Docker Swarm:

services:
  nginx:
    image: australproject/nginx:1.28
    user: "3001:3001"
    volumes:
      - /home/owner/websites/example.com:/home/www-data/website:ro

The configuration is rendered at start-up into /tmp/nginx (writable by any user). Use the same UID/GID as the PHP service so both read the same files. As root, workers run as www-data (legacy behaviour).

Listening on port 80 as non-root works on current Docker versions. If it fails with Permission denied, set LISTEN_PORT=8080 and update the Traefik port label.

Quick test:

docker run --rm -u 3001:3001 -e MODE=static -p 8080:80 australproject/nginx:1.28
curl -i http://127.0.0.1:8080/healthz

⁠Environment variables

⁠Cache and headers

• Static files whose name contains a hash (app.3f2a9c1b.js, app-3f2a9c1b.css): public, max-age=31536000, immutable
• Other static files: public, max-age=CACHE_STATIC_MAX_AGE
• HTML files: no-cache (always revalidated, so a new deployment is seen immediately)
• Static files served directly also carry the header Austral: Direct-Link
• Security headers on every response: X-Frame-Options, X-Content-Type-Options: nosniff, Referrer-Policy
• Hidden files (.git, .env, .htaccess, ...) return 404, except /.well-known/
• A missing static file is handled by the application (MODE=php), so dynamic robots.txt or generated images keep working

Gzip is always enabled, and Brotli when the module is installed.

⁠Overriding the configuration

Mount a directory on /overrides (read-only is fine):

# /overrides/server.d/redirect.conf
location = /old-page { return 301 /new-page; }

⁠Error pages

Errors generated by nginx (403, 404 on static sites, 413 upload too large, 502/503/504 when PHP is down or too slow...) use styled pages: 400 401 403 404 405 408 413 414 429 500 501 502 503 504. Errors returned by the PHP application itself (the Symfony or WordPress 404/500 pages) are left untouched.

To use your own pages, mount a directory on /overrides/errors:

volumes:
  - ./error-pages:/overrides/errors:ro

The HTTP status code is kept (a 404 page is still sent with a 404 status). Use absolute paths starting with /__errors/ for your assets.

⁠Health check

GET /healthz returns 200 ok and is not logged. The image healthcheck uses it.

⁠Logs

Access and error logs go to the container output (docker logs). Behind Traefik, the real client IP is read from X-Forwarded-For (REAL_IP_FROM).

⁠Commit Messages

The commit message must follow the Conventional Commits specification⁠. The following types are allowed:

• update: Update
• fix: Bug fix
• feat: New feature
• docs: Change in the documentation
• spec: Spec change
• test: Test-related change
• perf: Performance optimization

Examples:

update : Something

fix: Fix something

feat: Introduce X

docs: Add docs for X

spec: Z disambiguation

⁠License and Copyright

See License⁠

⁠Credits

Created by Matthieu Beurel⁠. Sponsored by Yipikai Studio⁠.