Nginx Configuration

The docker-openresty images are designed to make Nginx configuration straightforward and flexible.

Default Configuration Structure

The main Nginx configuration file is located at /usr/local/openresty/nginx/conf/nginx.conf. This file is intentionally kept minimal and includes configurations from another directory.

The key directive in nginx.conf is:

http {
    # ... other http directives ...

    include /etc/nginx/conf.d/*.conf;
}

include /etc/nginx/conf.d/*.main;

This setup provides two extension points:

  1. *.conf files: Any file ending in .conf inside /etc/nginx/conf.d/ will be included within the http block. This is the standard place for your server block configurations (virtual hosts).
  2. *.main files: Any file ending in .main inside /etc/nginx/conf.d/ will be included at the main (top) level of the configuration. This is useful for directives that must exist outside the http block, such as stream for TCP/UDP proxying or events.

By default, the image includes a file at /etc/nginx/conf.d/default.conf which contains a basic server configuration listening on port 80.

Providing Custom Configurations

The recommended way to provide your custom Nginx configuration is to mount a directory from your host machine to /etc/nginx/conf.d in the container. This will replace the default.conf and allow you to supply your own set of virtual hosts.

Example

Suppose you have a local directory my-nginx-conf with your app.conf:

.my-nginx-conf/
└── app.conf

Your app.conf might look like this:

server {
    listen 80;
    server_name myapp.com;

    location / {
        content_by_lua_block {
            ngx.say("Hello, Custom Config!")
        }
    }
}

You can run the container with this configuration:

docker run --rm -d -p 8080:80 \
  -v $(pwd)/my-nginx-conf:/etc/nginx/conf.d:ro \
  openresty/openresty:bookworm

Now, requests to http://localhost:8080 will be handled by your custom Lua block.

Note for SELinux Users

If you are running on a host with SELinux enabled (like CentOS or Fedora), you may need to add the :Z flag to the volume mount to relabel the files correctly for the container:

docker run -v $(pwd)/my-nginx-conf:/etc/nginx/conf.d:Z ...

Logging

For containerized environments, it's standard practice to log to stdout and stderr. The docker-openresty images facilitate this by symlinking the default Nginx log files:

  • access.log -> /dev/stdout
  • error.log -> /dev/stderr

This is done in the base image with these commands: 

ln -sf /dev/stdout /usr/local/openresty/nginx/logs/access.log
ln -sf /dev/stderr /usr/local/openresty/nginx/logs/error.log

If you change the log paths in your custom nginx.conf, docker logs will no longer capture your output unless you create similar symlinks.

Temporary File Paths

By default, Nginx writes temporary files for things like large client request bodies or proxy responses to disk. To avoid writing to the container's ephemeral filesystem, these paths are directed to a dedicated directory at /var/run/openresty/.

From nginx.conf: 

client_body_temp_path /var/run/openresty/nginx-client-body;
proxy_temp_path       /var/run/openresty/nginx-proxy;
fastcgi_temp_path     /var/run/openresty/nginx-fastcgi;
uwsgi_temp_path       /var/run/openresty/nginx-uwsgi;
scgi_temp_path        /var/run/openresty/nginx-scgi;

You may consider mounting /var/run/openresty as a tmpfs volume for better performance if you handle large file uploads or proxied requests.

Note: This feature does not apply to the Windows images.