NGINX Host

A Docker container used to easily create a secure NGINX server that is capable of hosting one or more Docker-based "units" of functionality, such as static content or web applications.

Features

• NGINX 1.10.3
• Designed to make creating an HTTPS server simple -- simply pick the parts you need.
• Default SSL settings score an A+ grade on SSL Labs when including custom Diffie-Hellman parameters.
• Designed to be used with Let's Encrypt certificates.
  • Certificates are automatically renewed.
• Default header settings score a B grade on securityheaders.io.
  • Score can be improved with the addition of Content Security Policy headers and HTTP Public Key Pinning.

Available Units

The following units are available -- simply pick and choose which ones you want to sit behind your NGINX server:

Unit	Description
bamboo	The Atlassian Bamboo continuous integration server.
bitbucket	The Atlassian Bitbucket Server collaborative Git server.
confluence	The Atlassian Confluence team collaboration server.
go-import-redirector	A unit based off of rsc/go-import-redirector, which simplifies the hosting of Go custom remote import paths.
hugo	The Hugo static site generator, designed for sites whose source code is hosted on GitHub. Includes the ability to regenerate the site whenever you push a commit.
hugo-extras	An enhanced version of the Hugo unit which contains extra tools.
jira	The Atlassian JIRA software development tool.
static	A unit that hosts simple static content.
webhook	A unit based off of adnanh/webhook, which allows you to execute arbitrary commands whenever a particular URL is accessed.

Usage

Prerequisites

Docker

• Docker 1.13 or newer
• Docker Compose 1.10.0 or newer
  • docker-compose.yml must declare version 2.1 or later

SSL Certificates

You must obtain SSL certificates from Let's Encrypt by following the getting started guide. Don't worry about writing a renewal script -- this Docker container handles that for you.

A Note on Certificate Directory Names and Units

Keep in mind that Let's Encrypt certificates are registered in terms of single hostnames and the directory structure it creates will reflect that. For example, if you create a certificate for mysite.com, Let's Encrypt will create a directory named /etc/letsencrypt/live/mysite.com. As long as the units you use are configured to be served from that same host (via NGINX_UNIT_HOSTS environment variable), there will be no problem.

However, you can configure units to be served from multiple discrete hosts, via wildcard, etc. Consider a unit that is served from *.mysite.com and othersite.com by setting the environment variable NGINX_UNIT_HOSTS=*.mysite.com,othersite.com. NGINX Host will attempt to look for the certificate in the directory /etc/letsencrypt/live/*.mysite.com,othersite.com. Since no such directory exists (after all, you registered your certificate against mysite.com), NGINX Host won't be able to find your certificate. To fix this, you need to create a symbolic link in your local /etc/letsencrypt directory from *.mysite.com,othersite.com to mysite.com.

Custom Diffie-Hellman parameters

Though not required, it is strongly recommended that you create custom Diffie-Hellman parameters for added security. If you're unsure how to do this, please follow this guide.

Configuration

It is highly recommended that you use Docker orchestration software such as Docker Compose as any NGINX Host setup you are likely to use will involve several Docker containers. This guide will assume that you are using Docker Compose.

To begin, let's create a docker-compose.yml file that contains the bare minimum set of services and volumes required:

version: "2.1"

volumes:
  data:

services:
  host:
    image: handcraftedbits/nginx-host
    ports:
      - "443:443"
    volumes:
      - data:/opt/container/shared
      - /etc/letsencrypt:/etc/letsencrypt
      - /home/me/dhparam.pem:/etc/ssl/dhparam.pem

The host service creates an instance of NGINX Host, listening on port 443. If you wish, you can also listen on port 80 and NGINX Host will automatically redirect HTTP requests to HTTPS.

Next, we mount the following volumes:

• data: a volume used to share information between NGINX Host and its units. This volume must always be mounted to /opt/container/shared.
• /etc/letsencrypt: the location of your Let's Encrypt certificates and renewal information. Typically this will be located in the /etc/letsencrypt directory on your local system.
• /etc/ssl/dhparam.pem: the file containing your custom Diffie-Hellman parameters. Note that this volume does not have to be mounted, but it is highly recommended to do so in the interest of increased security.

Adding Units

The configuration we created in the previous section will start an NGINX server but is not particularly useful as it hosts nothing. To fix that, let's add some static content by adding the static unit (shown here as the mysite service):

version: "2.1"

volumes:
  data:

services:
  mysite:
    image: handcraftedbits/nginx-unit-static
    environment:
      - NGINX_UNIT_HOSTS=mysite.com
      - NGINX_URL_PREFIX=/
    volumes:
      - data:/opt/container/shared
      - /home/me/mysite:/opt/container/www-static

  proxy:
    image: handcraftedbits/nginx-host
    links:
      - mysite
    ports:
      - "443:443"
    volumes:
      - data:/opt/container/shared
      - /etc/letsencrypt:/etc/letsencrypt
      - /home/me/dhparam.pem:/etc/ssl/dhparam.pem

The NGINX_UNIT_HOSTS environment variable specifies that we will be listening for requests to mysite.com and the NGINX_URL_PREFIX environment variable specifies that all static content will be available under /. Finally, we mount the local directory /home/me/mysite as the root of our static content (for more information on configuring the static unit, refer to the documentation).

Note that we must add a link in the proxy service to each unit that NGINX Host will host. In this case, we add a link to the mysite service.

There's more to NGINX Host than just static content though -- there are several units you can mix and match to create your ideal server. Consult the appropriate unit documentation for more information.

Additional NGINX Configuration

Additional configuration at the virtual host level (i.e., within a server block) can be added by mounting a file containing additional NGINX directives via the location /etc/nginx/extra/${hosts}.extra.conf. For example, if you have a unit hosted on *.mysite.com and othersite.com with additional NGINX directives located in the file /home/me/myextra.conf, you would add the volume /home/me/myextra.com:/etc/nginx/extra/*.mysite.com,othersite.com.extra.conf to the docker run command used to run the NGINX Host container.

You can also add additional configuration at a higher level (in this case, within the http block) by mounting a file containing additional NGINX directives via the location /etc/nginx/extra.conf. For example, if you have additional NGINX directives located in the file /home/me/nginxextra.conf, you would add the volume /home/me/nginxextra.conf:/etc/nginx/extra.conf to the docker run command used to run the NGINX host container.

Running NGINX Host

Assuming you are using Docker Compose, simply run docker-compose up in the same directory as your docker-compose.yml file. Otherwise, you will need to start each container with docker run or a suitable alternative, making sure to add the appropriate environment variables and volume references.

Reference

Environment Variables

Units

The following environment variables are required by all units (please consult unit documentation for any additional environment variables that may be required):

NGINX_UNIT_HOSTS

A comma-delimited list used to specify which virtual server or virtual servers will host the unit. In terms of NGINX configuration, this environment variable is used for the server_name directive and follows the same syntax, with the exception that the values are comma-delimited.

Required

NGINX_URL_PREFIX

The URL prefix to use. Combined with the NGINX_UNIT_HOSTS environment variable, this determines the full URL used to access the unit. For example, using NGINX_UNIT_HOSTS=mysite.com and NGINX_URL_PREFIX=/site would cause unit content to be served via the URL https://mysite.com/site.

Required

NGINX

The following environment variables are used to configure the NGINX server used by NGINX Host:

NGINX_GZIP

Used to set the value of the NGINX gzip directive.

Default value: on

NGINX_HEADERS_REMOVE

A comma-delimited list used to specify which header or headers will be removed from all responses. This is generally used for security purposes by removing headers that identify the server.

Default value: Server,X-Powered-By

NGINX_KEEPALIVE_TIMEOUT

Used to set the value of the NGINX keepalive_timeout directive.

Default value: 65

NGINX_PROXY_READ_TIMEOUT

Used to set the value of the NGINX proxy_read_timeout directive.

Default value: 120s

NGINX_RESOLVER

Used to set the value of the NGINX resolver directive.

Default value: 8.8.8.8 8.8.4.4

NGINX_TYPES_HASH_MAX_SIZE

Used to set the value of the NGINX types_hash_max_size directive.

Default value: 2048

NGINX_UNIT_WAIT

Used to set the time, in seconds, that NGINX Host will wait for units to launch. The value only needs to be changed if a particular unit takes an excessively long time to launch.

Default value: 2

NGINX_WORKER_CONNECTIONS

Used to set the value of the NGINX worker_connections directive.

Default value: 768

NGINX_WORKER_PROCESSES

Used to set the value of the NGINX worker_processes directive.

Default value: auto

NGINX_WWW_REDIRECT_HOSTS

A comma-delimited list used to specify which host(s) will have a www to non-www redirect added automatically. This is useful if you want to force the use of "naked" (non-www) domains. Note that you cannot use wildcards for this environment variable.