#nginx-ssl-proxy This repository is used to build a Docker image that acts as an HTTP reverse proxy with optional (but strongly encouraged) support for acting as an SSL termination proxy. The proxy can also be configured to enforce HTTP basic access authentication. Nginx is the HTTP server, and its SSL configuration is included (and may be modified to suit your needs) at nginx/proxy_ssl.conf in this repository.

Building the Image

Build the image yourself by cloning this repository then running:

docker build -t g5search/nginx-ssl-proxy .

Tagging and Releasing the Image

Releases should be tagged, both in git and in Docker, and the CHANGELOG updated. Please create a GitHub release to go along with your tag. We will use semantic versioning. In addition to git tags, a "floating" tag for non-breaking changes should be used in Docker. An example:

% git tag v1.2.3
% docker build -t g5search/nginx-ssl-proxy .
... many things ...
Successfully built 123ABC
% docker tag 123ABC g5search/nginx-ssl-proxy:v1.2.3
% docker tag 123ABC g5search/nginx-ssl-proxy:v1.2

The point here is that with each non-breaking patch release of the proxy server, the v1.2 Docker tag will be forced over with the latest version. Any subsequent releases of apps that use that tag will get the update. The explicit full version tag tag is still available for highly paranoid people, and should not get written over. If we're careful, we can deliver bugfixes and improvements to apps without having to touch each one.

If you do introduce breaking changes, increment the minor or major version so that you will not break anyone on their next deploy. You have a safety net because of Kubernetes health checks, but don't abuse your coworkers. Or try not to.

Beware After This Point

This is the remainder of the README. The majority of this is unchanged from how it was when I forked it. It may not reflect exactly how our forked version works. I will endeavor to update it properly. The "Using with Kubernetes" section doesn't reflect how we integrate it with our deployments.

Using with Kubernetes

This image is optimized for use in a Kubernetes cluster to provide SSL termination for other services in the cluster. It should be deployed as a Kubernetes replication controller with a service and public load balancer in front of it. SSL certificates, keys, and other secrets are managed via the Kubernetes Secrets API.

Here's how the replication controller and service would function terminating SSL for Jenkins in a Kubernetes cluster:

See https://github.com/GoogleCloudPlatform/kube-jenkins-imager for a complete tutorial that uses the nginx-ssl-proxy in Kubernetes.

Run an SSL Termination Proxy from the CLI

To run an SSL termination proxy you must have an existing SSL certificate and key. These instructions assume they are stored at /path/to/secrets/ and named cert.crt and key.pem. You'll need to change those values based on your actual file path and names.

1. Create a DHE Param

   The nginx SSL configuration for this image also requires that you generate your own DHE parameter. It's easy and takes just a few minutes to complete:

   openssl dhparam -out /path/to/secrets/dhparam.pem 2048

2. Launch a Container

   Modify the below command to include the actual address or host name you want to proxy to, as well as the correct /path/to/secrets for your certificate, key, and dhparam:

   docker run \
     -e ENABLE_SSL=true \
     -e TARGET_SERVICE=THE_ADDRESS_OR_HOST_YOU_ARE_PROXYING_TO \
     -v /path/to/secrets/cert.crt:/etc/secrets/proxycert \
     -v /path/to/secrets/key.pem:/etc/secrets/proxykey \
     -v /path/to/secrets/dhparam.pem:/etc/secrets/dhparam \
     g5search/nginx-ssl-proxy

   The really important thing here is that you map in your cert to /etc/secrets/proxycert, your key to /etc/secrets/proxykey, and your dhparam to /etc/secrets/dhparam as shown in the command above.

3. Enable Basic Access Authentication

   Create an htpaddwd file:

   htpasswd -nb YOUR_USERNAME SUPER_SECRET_PASSWORD > /path/to/secrets/htpasswd

   Launch the container, enabling the feature and mapping in the htpasswd file:

   docker run \
     -e ENABLE_SSL=true \
     -e ENABLE_BASIC_AUTH=true \
     -e TARGET_SERVICE=THE_ADDRESS_OR_HOST_YOU_ARE_PROXYING_TO \
     -v /path/to/secrets/cert.crt:/etc/secrets/proxycert \
     -v /path/to/secrets/key.pem:/etc/secrets/proxykey \
     -v /path/to/secrets/dhparam.pem:/etc/secrets/dhparam \
     -v /path/to/secrets/htpasswd:/etc/secrets/htpasswd \
     g5search/nginx-ssl-proxy

4. Disabling HTTP/2

HTTP/2 is on by default when using SSL. To disable it, set the DISABLE_HTTP2 environment variable to true.

4. Add additional nginx config

   All *.conf from nginx/extra are added during built to /etc/nginx/extra-conf.d and get included on startup of the container. Using volumes you can overwrite them on start of the container:

   docker run \
     -e ENABLE_SSL=true \
     -e TARGET_SERVICE=THE_ADDRESS_OR_HOST_YOU_ARE_PROXYING_TO \
     -v /path/to/secrets/cert.crt:/etc/secrets/proxycert \
     -v /path/to/secrets/key.pem:/etc/secrets/proxykey \
     -v /path/to/secrets/dhparam.pem:/etc/secrets/dhparam \
     -v /path/to/additional-nginx.conf:/etc/nginx/extra-conf.d/additional_proxy.conf \
     g5search/nginx-ssl-proxy

   That way it is possible to setup additional proxies or modifying the nginx configuration.