Public Repository

Last pushed: 22 days ago
Short Description
Nginx
Full Description

Nginx Docker Image

Why should I use this image (vs. the official image)?

It provides multiple customization options and configuration templates.

Healthcare Blocks customers can also use this image in their development environment.

Image Info / Versions

Base image: Healthcare Blocks Debian

The "Alpine" tagged images are based on Healthcare Blocks Alpine are currently experimental.

Versions: https://hub.docker.com/r/healthcareblocks/nginx/tags/

Note: The latest tag is always associated with a stable - not mainline - version. See http://nginx.org/.

Running

docker run -dP healthcareblocks/nginx

Binds random ports on the host to the container's ports 80 and 443
(allows you to run multiple Nginx containers, if needed).

docker run -d -p 80:80 -p 443:443 healthcareblocks/nginx

Bind ports 80 and 443 on the host to the Nginx container.

Static Files

You might need to mount the html directory to a host directory
containing static HTML files:

docker run -v /data/nginx/html:/nginx/html -dP healthcareblocks/nginx

Another technique involves mounting to another container's exposed volume that has
static files already included.

docker run --volumes-from app_container -dP healthcareblocks/nginx

Customizing Nginx's Configuration

The stock configuration uses sensible defaults but you can easily
modify them using one or more techniques:

Environment Variables

During runtime, a new configuration file (/nginx/conf/nginx.conf) is generated
based on /nginx/conf/nginx.conf.tpl. Certain parameters, that are likely to
change for specific workloads, are exposed as Docker environment variables,
whose defaults are embedded towards the bottom of the Dockerfile.

You can override the defaults at runtime by passing -e or --env-file to docker run.

Mounting External Config Files

The configuration directory (/nginx/conf) also contains files that are included
by the main nginx.conf, for example, mime.types and ssl.conf. If you need to override their
contents, create a copy of the file on the host and then mount the file:

docker run -v /data/nginx/mime.types:/nginx/conf/mime.types -dP healthcareblocks/nginx
Specifying an Application-Specific Server Configuration

The NGINX_SERVER_TYPE environment variable allows you to switch between several
common variations:

  • default (standard backend proxy)
  • static (for serving static html files)
  • php
  • uwsgi
  • proxy (reverse proxy only, no static file serving)

The default, php, uwsgi, and proxy options assume you have another container running your
favorite Web framework, as the backend process. You might need to override the
NGINX_BACKEND_SERVER_ADDRESS and NGINX_BACKEND_SERVER_PORT settings.

If you don't want to use any of the canned server templates, create and mount your own:

docker run -v /data/nginx/server_type.default.tpl:/nginx/conf/server_type.default.tpl \
           -dP healthcareblocks/nginx
Including Additional Settings

Extend the stock configuration by mounting http.extend.conf and/or server.extend.conf:

docker run -v /data/nginx/http.extend.conf:/nginx/conf/http.extend.conf \
           -v /data/nginx/server.extend.conf:/nginx/conf/server.extend.conf \
           -dP healthcareblocks/nginx

SSL

The default config under conf/ssl.conf is biased towards strong security (i.e. modern browsers)
following the guidance in https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html.

A self-signed certificate for docker.local is included in the ssl directory.

Required Steps for Production Environments

When using this Docker image in production, be sure you do the following:

  1. Generate your own Diffie-Hellman parameter (on the host):

    cd /etc/ssl/certs/
    openssl dhparam -out dhparam.pem 4096
    
  2. Obtain a real SSL certificate from a Certificate Authority. Or for internal (trusted)
    networks, create your own root CA certificate and an application certificate. Save
    as app.crt and app.key in /etc/ssl/ (or wherever you prefer) on the host machine.

  3. Then, when running the container, mount key and cert to their container equivalents.

    docker run -v /etc/ssl/certs/dhparam.pem:/nginx/ssl/dhparam.pem \
            -v /etc/ssl/certs/app.crt:/nginx/ssl/app.crt \
            -v /etc/ssl/private/app.key:/nginx/ssl/app.key \
            -dP healthcareblocks/nginx
    

Viewing Logs

Tail logs via the Docker client:

docker logs -f container_name

Or mount the logs directory outside of the container to access them directly:

docker run -v /data/nginx/logs:/nginx/logs -dP healthcareblocks/nginx

Example Docker Compose File for Production Use

# docker-compose.yml

nginx:
  image: healthcareblocks/nginx
  links:
    - app
  environment:
    NGINX_BACKEND_SERVER_ADDRESS: app_1
    NGINX_BACKEND_SERVER_PORT: 3000
    NGINX_SERVER_NAME: docker.local
    NGINX_ROOT_DIR: /app/public
  ports:
    - "80:80"
    - "443:443"
  restart: always
  volumes:
    - /etc/ssl/certs/dhparam.pem:/nginx/ssl/dhparam.pem
    - /etc/ssl/certs/app.crt:/nginx/ssl/app.crt
    - /etc/ssl/private/app.key:/nginx/ssl/app.key
  volumes_from:
    - app

app:
  image: my_namespace/my_app
  expose:
    - "3000"
  restart: always

Dockerfile

FROM healthcareblocks/debian:latest
MAINTAINER Healthcare Blocks <ops@healthcareblocks.com>

COPY *.txt /hcb/manifest/

ENV NGINX_VERS 1.9.10
ENV NGINX_SHA2 fb14d76844cab0a5a0880768be28965e74f9956790f618c454ef6098e26631d9

WORKDIR /usr/local/src

RUN \
  curl -fL http://nginx.org/download/nginx-$NGINX_VERS.tar.gz -o nginx.tar.gz && \
  hcb fingerprint sha256 $NGINX_SHA2 nginx.tar.gz && \
  tar xzf nginx.tar.gz && rm nginx.tar.gz && \

  hcb install build_dependencies && \

  cd nginx-$NGINX_VERS && \
  ./configure \
    --prefix=/nginx \
    --sbin-path=/sbin/nginx \
    --pid-path=/nginx/run/nginx.pid \
    --with-http_auth_request_module \
    --with-http_gzip_static_module \
    --with-http_realip_module \
    --with-http_ssl_module \
    --with-ipv6 && \
  make && make install && \
  rm -fr nginx-$NGINX_VERS /usr/local/src/nginx* && \

  hcb cleanup

RUN groupadd -r nginx && useradd -r -g nginx nginx

WORKDIR /nginx
RUN rm -fr conf
COPY conf /nginx/conf/
COPY ssl /nginx/ssl/

RUN ln -sf /dev/stdout /nginx/logs/access.log
RUN ln -sf /dev/stderr /nginx/logs/error.log

EXPOSE 80 443

ENV NGINX_BACKEND_SERVER_ADDRESS localhost
ENV NGINX_BACKEND_SERVER_PORT 3000
ENV NGINX_KEEPALIVE_TIMEOUT 75s
ENV NGINX_ROOT_DIR html
ENV NGINX_SERVER_NAME _
ENV NGINX_SERVER_NAMES_HASH_BUCKET_SIZE 128
ENV NGINX_SERVER_TYPE default
ENV NGINX_WORKER_CONNECTIONS 1024
ENV NGINX_WORKER_PROCESSES auto

COPY docker-entrypoint.sh /
RUN hcb secure

ENTRYPOINT ["/docker-entrypoint.sh"]
CMD ["nginx"]
Docker Pull Command
Owner
healthcareblocks