bunkerweb/docs/integrations.md

Integrations

Docker

Introduction

You can get official prebuilt Docker images of bunkerized-nginx for x86, x64, armv7 and aarch64/arm64 architectures on Docker Hub :

$ docker pull bunkerity/bunkerized-nginx

Or you can build it from source if you wish :

$ git clone https://github.com/bunkerity/bunkerized-nginx.git
$ cd bunkerized-nginx
$ docker build -t bunkerized-nginx .

To use bunkerized-nginx as a Docker container you have to pass specific environment variables, mount volumes and redirect ports to make it accessible from the outside.

Basic usage

To demonstrate the use of the Docker image, we will create a simple "Hello World" static file that will be served by bunkerized-nginx.

One important thing to know is that the container runs as an unprivileged user with UID and GID 101. The reason behind this behavior is the security : in case a vulnerability is exploited the attacker won't have full privileges. But there is also a downside because bunkerized-nginx (heavily) make use of volumes, you will need to adjust the rights on the host.

First create the environment on the host :

$ mkdir bunkerized-hello bunkerized-hello/www bunkerized-hello/certs
$ cd bunkerized-hello
$ chown root:101 www certs
$ chmod 750 www
$ chmod 770 certs

The www folder will contain our static files that will be served by bunkerized-nginx. Whereas the certs folder will store the automatically generated Let's Encrypt certificates.

Let's create a dummy static page into the www folder :

$ echo "Hello bunkerized World !" > www/index.html
$ chown root:101 www/index.html
$ chmod 740 www/index.html

It's time to run the container :

$ docker run \
         -p 80:8080 \
         -p 443:8443 \
         -v "${PWD}/www:/www:ro" \
         -v "${PWD}/certs:/etc/letsencrypt" \
         -e SERVER_NAME=www.example.com \
         -e AUTO_LETS_ENCRYPT=yes \
         bunkerity/bunkerized-nginx

Or if you prefer docker-compose :

version: '3'
services:
  mybunkerized:
    image: bunkerity/bunkerized-nginx
    ports:
      - 80:8080
      - 443:8443
    volumes:
      - ./www:/www:ro
      - ./certs:/etc/letsencrypt
    environment:
      - SERVER_NAME=www.example.com
      - AUTO_LETS_ENCRYPT=yes

Important things to note :

• Replace www.example.com with your own domain (it must points to your server IP address if you want Let's Encrypt to work)
• Automatic Let's Encrypt is enabled thanks to AUTO_LETS_ENCRYPT=yes (since the default is AUTO_LETS_ENCRYPT=no you can remove the environment variable to disable Let's Encrypt)
• The container is exposing TCP/8080 for HTTP and TCP/8443 for HTTPS
• The /www volume can be mounted as read-only for security reason whereas the /etc/letsencrypt one must be mounted as read/write

Inspect the container logs until bunkerized-nginx is started then visit http(s)://www.example.com to confirm that everything is working as expected.

This example is really simple but, as you can see in the list of environment variables, you may get a lot of environment variables depending on your use case. To make things cleanier, you can write the environment variables to a file :

$ cat variables.env
SERVER_NAME=www.example.com
AUTO_LETS_ENCRYPT=yes

And load the file when creating the container :

$ docker run ... --env-file "${PWD}/variables.env" ... bunkerity/bunkerized-nginx

Or if you prefer docker-compose :

...
services:
  mybunkerized:
    ...
    env_file:
      - ./variables.env
    ...
...

Autoconf

Docker Swarm

Kubernetes

Linux