oauthq/nginx repository overview

⁠oauthq/nginx

A lightweight Nginx runtime image based on the official nginx:stable-alpine image.

Designed for serving static files, reverse proxying, and running in front of PHP-FPM applications such as Laravel.

⁠Features

• Based on the official Nginx stable Alpine image
• Automatic worker process configuration
• Gzip compression enabled for common text formats
• server_tokens disabled
• Error logs written to container stderr
• Access logs disabled by default
• Nginx worker runs with UID/GID 1000
• Dynamic module configuration support
• Optional HTTP healthcheck helper
• Keeps the official Nginx welcome site by default
• No application source code included

⁠Available tags

⁠Quick start

docker pull oauthq/nginx:stable

docker run --rm \
  --name nginx \
  -p 8080:80 \
  oauthq/nginx:stable

Open:

http://127.0.0.1:8080

The base image retains the official Nginx welcome site. Applications should replace /etc/nginx/conf.d/default.conf with their own server configuration.

⁠Serve static files

Example default.conf:

server {
    listen 80;
    listen [::]:80;
    server_name _;

    root /var/www/html/public;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Run the container:

docker run --rm \
  --name nginx \
  -p 8080:80 \
  -v "$(pwd)/default.conf:/etc/nginx/conf.d/default.conf:ro" \
  -v "$(pwd)/public:/var/www/html/public:ro" \
  oauthq/nginx:stable

⁠Use with PHP-FPM

Example configuration for a PHP or Laravel application:

server {
    listen 80;
    listen [::]:80;
    server_name _;

    root /var/www/html/public;
    index index.php index.html;

    client_max_body_size 35m;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        try_files $uri =404;

        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $document_root;

        fastcgi_pass php:9000;
    }

    location ~ /\. {
        deny all;
    }
}

The php hostname should match the PHP-FPM service name on the Docker network.

⁠Healthcheck

The image does not declare a built-in Docker HEALTHCHECK, because the final route and readiness requirements belong to the downstream application.

An optional helper is included:

docker exec nginx nginx-healthcheck

Docker Compose example:

healthcheck:
  test: ["CMD", "nginx-healthcheck"]
  interval: 10s
  timeout: 3s
  retries: 3

The default healthcheck URL is:

http://127.0.0.1:80/

It can be overridden:

environment:
  NGINX_HEALTHCHECK_URL: http://127.0.0.1/healthz

⁠Logging

Nginx error logs are available through:

docker logs nginx

Access logging is disabled by default. Enable it in a downstream server configuration when required:

access_log /var/log/nginx/access.log main;

The access log path is connected to container stdout.

⁠Important paths

⁠Validate configuration

docker run --rm oauthq/nginx:stable nginx -t

For a running container:

docker exec nginx nginx -t

⁠License

MIT