Custom config in Docker in Nginx - Commands & Configuration

Introduction

Sometimes you want to change how a program inside a Docker container works by giving it your own settings. This helps you control the program without changing the container itself.

When you want to change the website settings served by nginx inside a Docker container.

When you need to add custom rules like redirects or security headers to nginx running in Docker.

When you want to test different nginx configurations without rebuilding the whole Docker image.

When you want to keep your configuration files separate from the Docker image for easier updates.

When you want to share the same Docker image but use different settings on different servers.

Config File - nginx.conf

nginx.conf

events {}
http {
    server {
        listen 80;
        server_name localhost;

        location / {
            root /usr/share/nginx/html;
            index index.html index.htm;
        }

        location /hello {
            add_header Content-Type text/plain;
            return 200 'Hello from custom config!';
        }
    }
}

This file tells nginx to listen on port 80 and serve files from the default html folder. It also adds a new path /hello that returns a simple text message. This shows how you can add custom behavior with your own config.

Commands

This command runs the official nginx container in the background and maps port 8080 on your computer to port 80 inside the container. It uses the default nginx settings.

Terminal

docker run --name my-nginx -d -p 8080:80 nginx

Expected Output

a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef0

→

--name - Gives the container a name for easy reference

→

-d - Runs the container in the background

→

-p - Maps a port from host to container

This copies your custom nginx.conf file from your computer into the running container, replacing the default config with your custom one.

Terminal

docker cp nginx.conf my-nginx:/etc/nginx/nginx.conf

Expected Output

No output (command runs silently)

This tells nginx inside the container to reload its configuration without stopping the container. It applies your new settings immediately.

Terminal

docker exec my-nginx nginx -s reload

Expected Output

No output (command runs silently)

This command checks if your custom config works by requesting the /hello path from nginx running in Docker. It should return your custom message.

Terminal

curl -i http://localhost:8080/hello

Expected Output

HTTP/1.1 200 OK

Server: nginx/1.23.3

Date: Thu, 01 Jun 2023 12:00:00 GMT

Content-Type: text/plain

Content-Length: 24

Connection: keep-alive



Hello from custom config!

→

-i - Includes HTTP headers in the output

Key Concept

If you remember nothing else from this pattern, remember: you can change how a program inside Docker works by copying your own config file into the container and reloading it.

Common Mistakes

Not copying the config file into the container before reloading nginx.

Nginx keeps using the old config and your changes have no effect.

Always copy your custom config file into the container path before telling nginx to reload.

Reloading nginx without the config file being valid.

Nginx will fail to reload and keep the old config, or the container logs will show errors.

Check your config file syntax locally before copying, for example with 'nginx -t'.

Mapping the wrong port or forgetting to map ports when running the container.

You cannot access nginx from your computer because the ports are not connected.

Use '-p 8080:80' to map container port 80 to host port 8080 or another free port.

Summary

Run the nginx container with port mapping to access it from your computer.

Copy your custom nginx.conf file into the running container to replace default settings.

Reload nginx inside the container to apply your new configuration without restarting.

Test your custom config by requesting the new path you added.