Nginx Reverse-Proxy docker image

A docker image to run Nginx Reverse-Proxy as Kubernetes service.

Nginx website: nginx.org

Quick start

Clone this project:

git clone https://github.com/iconoeugen/docker-nginx.git
cd docker-nginx

Make your own Nginx Reverse-Proxy docker image

Build your image:

docker build -t dockernginx_nginx .

Run your image:

docker run --name dockernginx_test -p 8080:8080 --detach dockernginx_nginx

To Check running container access the URL: (http://localhost:8080/)

Stop running container:

docker stop dockernginx_test

Remove stopped container:

docker rm dockernginx_test

Docker compose

Compose is a tool for defining and running multi-container Docker applications, using a Compose file to configure the application services.

Build docker images:

docker-compose build

Create and start docker containers with compose:

docker-compose up -d

Stop docker containers

docker-compose stop

Removed stopped containers:

docker-compose rm

Environment Variables

Remote service

• SERVICE_BY_NAME Configure as reverse proxy upstream the Hostname value from SERVICE_NAME if set to 1 or true else use the IP address value from <SERVICE_NAME>_SERVICE_HOST. (Defaults: 1)
• SERVICE_NAME: Name of Service to be configured as reverse proxy. (Manadatory)
• SERVICE_PROTO: Upstream service protocol to be configured as reverse proxy. (Defaults: http)
• <SERVICE_NAME>_SERVICE_HOST: Service Hostname or IP to be configured as reverse proxy upstream as generated by Kubernetes when the target service is placed in the same namespace as the Nginx Reverse-Proxy service. (Manadatory)
• <SERVICE_NAME>_SERVICE_PORT: Service Port to be configured as reverse proxy upstream as generated by Kubernetes when the target service is placed in the same namespace as the Nginx Reverse-Proxy service. (Defaults: "")

The name of the host and port environment variable are dependent on the provided SERVICE_NAME value; i.e. if SERVICE_NAME=test then the service Hostname is test and the service IP address is lookedup in TEST_SERVICE_HOST environment variable while the Port number is lookedup in TEST_SERVICE_PORT environment variable. The service name is uppercased and - is replaced with _ when generating the environment variable name.

Nginx setup configuration

• NGINX_SETUP_SCRIPT: If this value points to an executable script present in the container instance then it will be executed before Nginx is started. (Defaults: empty)

Nginx core configuration

• NGINX_WORKER_PROCESSES: Defines the number of worker processes. (Defaults: 1)
• NGINX_WORKER_CONNECTIONS: Sets the maximum number of simultaneous connections that can be opened by a worker process. (Defaults: 512)

Nginx server configuration

• NGINX_SEND_TIMEOUT: Sets a timeout for transmitting a response to the client. (Defaults: 60s)
• NGINX_SENDFILE: Enables or disables the use of sendfile. Nginx option enables to use of sendfile(2) for everything related to… sending file. (Defaults: off)
• NGINX_TCP_NODELAY: Activating TCP_NODELAY forces a socket to send the data in its buffer, whatever the packet size. (Defaults: off)
• NGINX_TCP_NOPUSH: Enables or disables the use of the TCP_NOPUSH. tcp_nopush works as an opposite to tcp_nodelay. Instead of optimizing delays, it optimizes the amount of data sent at once. (Defaults: off)
• NGINX_KEEP_ALIVE_TIMEOUT: The first parameter sets a timeout during which a keep-alive client connection will stay open on the server side. The zero value disables keep-alive client connections. (Defaults: 75s)
• NGINX_CLIENT_HEADER_TIMEOUT: Defines a timeout for reading client request header. (Defaults: 8s)
• NGINX_CLIEHT_HEADER_BUFFER_SIZE: Sets buffer size for reading client request header. (Defaults: 8k)
• NGINX_LARGE_CLIENT_HEADER_BUFFERS_NUMBER: Sets the maximum number and size of buffers used for reading large client request header. (Defaults: 4)
• NGINX_LARGE_CLIENT_HEADER_BUFFERS_SIZE: Sets the maximum size of buffers used for reading large client request header. (Defaults: 8k)
• NGINX_CLIENT_BODY_TIMEOUT: Defines a timeout for reading client request body. The timeout is set only for a period between two successive read operations, not for the transmission of the whole request body. (Defaults: 8s)
• NGINX_CLIENT_BODY_BUFFER_SIZE: Sets buffer size for reading client request body. In case the request body is larger than the buffer, the whole body or only its part is written to a temporary file. (Defaults: 1k)

Nginx as HTTP proxy server

• NGINX_HTTP_ENABLED: Enable Nginx as HTTP proxy server to listen on port 8080 if value is 1. (Defaults: 1)

Nginx as HTTPS proxy server

• NGINX_HTTPS_ENABLED: Enable Nginx as HTTPS proxy server to listen on port 8443 if value is 1. (Defaults: 0)
• NGINX_SSL_DH_SIZE: Specifies the bit size of DH parameters. (Defaults: 128)
• NGINX_SSL_DH_PATH: Path to DH parameters file. (Defaults: /etc/nginx/certs/dh.pem)
• NGINX_SSL_CERT_PATH: Specifies a file with the certificate in the PEM format. If certificate file is not found then a new one is generated. (Defaults: /etc/nginx/certs/cert.pem)
• NGINX_SSL_KEY_PATH: Specifies a file with the secret key in the PEM format. If secret key file is not found then a new one is generated. (Defaults: /etc/nginx/certs/cert.key)

Nginx Status page

• NGINX_STATUS_ENABLED: Enable Nginx staus page if vaalue is 1. (Defaults: 0)
• NGINX_STATUS_LOCATION: Nginx location for status page to set the configuration depending on request URI. (Defaults: /nginx_status)
• NGINX_STATUS_ALLOW: Allows access to status page for the specified network or address. (Defaults: 127.0.0.1)
• NGINX_STATUS_DENY: Denies access too stau page for the specified network or address. (Defaults: all)

Other configurations

• DEBUG: Enable entrypoint debug output if value is 1. (Defaults: 0)

Set your own environment variables

Environment variables can be set by adding the --env argument in the command line, for example:

docker run \
  --env SERVICE_NAME="test" \
  --env TEST_SERVICE_HOST="google.com" \
  --env TEST_SERVICE_PORT="80" \
  --name dockernginx_test \
  --detach \
  dockernginx_nginx

Using external certificate files

The insertion of signed certificates in the container instance can be done in different ways depending on the runtime environment.

Docker at build time

Create a new Docker container that inherits FROM iconoeugen/docker-nginx and add the DH parameters, certificate and secret key files in the container during build phase.

FROM iconoeugen/docker-nginx

COPY /tmp/dh.pem /tmp/cert.key /tmp/cert.pem /

ENV NGINX_SSL_DH_PATH /dh.pem
ENV NGINX_SSL_CERT_PATH /cert.pem
ENV NGINX_SSL_KEY_PATH /cert.key

Docker at runtime

Mount the file in the Docker container running instance and configure the environment variables to point to the DH parameters, certificate and secret key files.

Now run the Docker container:

docker run \
  -v /tmp/dh.pem:/tmp/dh.pem \
  -v /tmp/cert.pem:/tmp/cert.pem \
  -v /tmp/cert.key:/tmp/cert.key \
  --env SERVICE_NAME="test" \
  --env TEST_SERVICE_HOST="google.com" \
  --env TEST_SERVICE_PORT="80" \
  --env NGINX_SSL_DH_PATH="/tmp/dh.pem" \
  --env NGINX_SSL_CERT_PATH="/tmp/cert.pem" \
  --env NGINX_SSL_KEY_PATH="/tmp/cert.key" \
  --name dockernginx_test \
  --detach \
  dockernginx_nginx

Kubernetes

The DH parameters, certificate and secret key files can be mounted as secrets and the environment variables configured to point to the secret files path.

Create self signed certificates

Create a Diffie-Hellman cert

You can use the following command:

openssl dhparam -out /tmp/dh.pem 256

Create a self-signed ssl cert.

Please note, that the Common Name (CN) is important and should be the FQDN to the secured server (in this example is 'localhost'):

openssl req -x509 -newkey rsa:4086 \
  -subj "/C=XX/ST=XXXX/L=XXXX/O=XXXX/CN=localhost" \
  -keyout "/etc/nginx/external/cert.key" \
  -out "/etc/nginx/external/cert.pem" \
  -days 3650 -nodes -sha256