docker-nginx

A Cube compatible service providing NGinx in a Docker container.

Key Features

• Secure defaults
• Automatic dhparam generation
• Easy to configure via YAML
• Consumes nginx-server roles

Requirements

The following applications must be installed on the host system in order to use Docker-NGinx:

• Docker (Must be able to connect to DockerHub)
• OpenSSL
• Python 3.4+ (Must be able to connect to https://pypi.org)

Getting started

$ cube products import --github git.niklasrosenstein.com:cube/docker-nginx@0.0.2
$ cube services create nginx
$ cube services install nginx docker-nginx@0.0.2
$ cube config update nginx -f nginx-overrides.yaml
$ cube services start nginx

Configuration

Example:

runtime:
  image: "nginx:latest"  # default
  http:
    ssl:
      certificate: /host/path/to/fullchain.pem
      certificate_key: /host/path/to/privkey.pem
      dhparam: auto,dsa,4096  # default
  ports:  # default is generated based on the "listen" directives of "nginx-server" roles
    - "80:80"
    - "443:443"

image

The name of the NGinx Docker image. Defaults to nginx:latest.

network

The Docker network to run the container on. Defaults to null. Can be set to host on Linux system to make network configuration easier when setting up NGinx proxy servers, but note that it renders ports ineffective.

ports

A list of Docker port mappings. If not specified, all ports listed in the listen option of nginx-server roles will be exposed to the host.

mounts

A list of additional mount specifiers for the Docker container.

http.ssl

SSL certificate configuration. If specified, SSL is globally available to all server blocks. The certificate and certificate_key must point to the full paths of the certificates on the host. The paths will be mounted as read-only in the container.

By default, the dhparam key defaults to auto,dsa,4096 which automatically generates dhparams on first startup. The key type can be dh instead of dsa for true Diffe-Hellman parameters, but the generation will be very slow. Alternatively, the value can point to a filename on the host (in which case the file will be mounted in the container).

Additional SSL parameters are available, see the SslConfiguration definition for more details. The following articles have been used as references for the safe default SSL configuration:

• raymii.org: Strong SSL Security on NGinx
• testssl.sh

http.includes

A list of files (in the container) to include in the configuration. Defaults to ["/etc/nginx/mime.types"].

http.settings

Arbitrary key-value pairs that are rendered in the http block. A number of default settings apply (see the NginxHttpSettings definition for more details).

events.settings

Arbitrary key-value pairs that are rendered in the events block. A number of default settings apply (see the NginxEventSettings definition for more details).

nginx-server Role Configuration

This role produces a server {} block in the NGinx configuration. Currently, it is mainly designed for proxy_pass configuration. Example:

produces:
- role: nginx-server
  force_https: true  # default is false
  hsts: true  # defaults to true if force_https is enabled or if the server has ssl configured
  server_name: example.org
  listen: 443 ssl
  proxy_pass:
    protocol: http
    servers:
    - localhost:{{conf.port}}

server_name (required)

NGinx server_name option. First value is used for the upstream name if a proxy_pass is configured. At least one server name must be specified, separated by whitespace.

listen (required)

The server's listen option, for example 80 or 443 ssl. Multiple listen options can be separated by commas, eg. 80,443 ssl.

force_https

Defaults to false. If enabled, will automaticlly redirect from http:// to https://.

hsts

Send the Strict-Transport-Security header with every response. Defaults to true if the server has SSL configured or force_https is enabled.

proxy_pass

Defines an upstream block and a proxy_pass option in the server block. The protocol and servers key must be provided. Adds a number of default headers to the proxied request unless set_default_headers is set to false. For more details, see the ProxyPassConfig definition.

---

Copyright © 2020 Niklas Rosenstein