diff --git a/README.md b/README.md index 90b342e..84070e8 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,8 @@ $ docker pull bunkerity/bunkerized-nginx Or you can build it from source if you wish : ```shell +$ git clone https://github.com/bunkerity/bunkerized-nginx.git +$ cd bunkerized-nginx $ docker build -t bunkerized-nginx . ``` diff --git a/docs/index.md b/docs/index.md index d9c6fb6..8348b8b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,10 +4,11 @@ :maxdepth: 2 :caption: Contents introduction +integrations quickstart_guide +special_folders security_tuning -troubleshooting -volumes environment_variables +troubleshooting plugins ``` diff --git a/docs/integrations.md b/docs/integrations.md new file mode 100644 index 0000000..670af54 --- /dev/null +++ b/docs/integrations.md @@ -0,0 +1,114 @@ +# Integrations + +## Docker + +### Introduction + +You can get official prebuilt Docker images of bunkerized-nginx for x86, x64, armv7 and aarch64/arm64 architectures on Docker Hub : +```shell +$ docker pull bunkerity/bunkerized-nginx +``` + +Or you can build it from source if you wish : +```shell +$ 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 : +```shell +$ 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 : +```shell +$ 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 : +```shell +$ 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 : +```yaml +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](#TODO), 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 : +```shell +$ cat variables.env +SERVER_NAME=www.example.com +AUTO_LETS_ENCRYPT=yes +``` + +And load the file when creating the container : +```shell +$ docker run ... --env-file "${PWD}/variables.env" ... bunkerity/bunkerized-nginx +``` + +Or if you prefer docker-compose : +```yaml +... +services: + mybunkerized: + ... + env_file: + - ./variables.env + ... +... +``` + +### Autoconf + +## Docker Swarm + +## Kubernetes + +## Linux diff --git a/docs/introduction.md b/docs/introduction.md index 22206d9..e0942c5 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,12 +1,14 @@ # Introduction

- +

-nginx Docker image secure by default. +> Make security by default great again ! -Avoid the hassle of following security best practices "by hand" each time you need a web server or reverse proxy. Bunkerized-nginx provides generic security configs, settings and tools so you don't need to do it yourself. +bunkerized-nginx is a web server based on the notorious nginx and focused on security. It integrates into existing environments (Linux, Docker, Swarm, Kubernetes, ...) to make your web services "secured by default" without any hassle. The security best practices are automatically applied for you while keeping control of every settings to meet your own use case. + + Non-exhaustive list of features : - HTTPS support with transparent Let's Encrypt automation @@ -15,15 +17,14 @@ Non-exhaustive list of features : - Automatic ban of strange behaviors - Antibot challenge through cookie, javascript, captcha or recaptcha v3 - Block TOR, proxies, bad user-agents, countries, ... -- Block known bad IP with DNSBL and CrowdSec +- Block known bad IP with DNSBL - Prevent bruteforce attacks with rate limiting -- Plugins system for external security checks (e.g. : ClamAV) +- Plugins system for external security checks (ClamAV, CrowdSec, ...) - Easy to configure with environment variables or web UI -- Automatic configuration with container labels -- Docker Swarm support +- Seamless integration into existing environments : Linux, Docker, Swarm, Kubernetes, ... Fooling automated tools/scanners : - + -You can find a live demo at https://demo-nginx.bunkerity.com, feel free to do some security tests. +You can find a live demo at https://demo-nginx.bunkerity.com, feel free to do some security tests. diff --git a/docs/special_folders.md b/docs/special_folders.md new file mode 100644 index 0000000..03f5d07 --- /dev/null +++ b/docs/special_folders.md @@ -0,0 +1,3 @@ +# Special folders + +TODO