docs - quickstart guide / reverse proxy

2021-08-10 23:39:28 +02:00 · 2021-08-10 23:39:28 +02:00 · 9e2a8070e4
parent 733136ac1a
commit 9e2a8070e4
3 changed files with 246 additions and 7 deletions
--- a/docs/index.md
+++ b/docs/index.md
@ -1,7 +1,6 @@
 # bunkerized-nginx official documentation

 ```{toctree}
-:maxdepth: 1
 :caption: Contents
 introduction
 integrations
--- a/docs/integrations.md
+++ b/docs/integrations.md
@ -106,12 +106,16 @@ services:
 ...
 ```

-### Autoconf
+## Docker autoconf
+
+### Introduction

 The downside of using environment variables is that the container needs to be recreated each time there is an update which is not very convenient. To counter that issue, you can use another image called bunkerized-nginx-autoconf which will listen for Docker events and automatically configure bunkerized-nginx instance in real time without recreating the container. Instead of defining environment variables for the bunkerized-nginx container, you simply add labels to your web services and bunkerized-nginx-autoconf will "automagically" take care of the rest.

 <img src="https://github.com/bunkerity/bunkerized-nginx/blob/dev/docs/img/autoconf-docker.png?raw=true" />

+### Usage
+
 First of all, you will need a network so autoconf and bunkerized-nginx can communicate and another one to allow communication between bunkerized-nginx and your web services :
 ```shell
 $ docker network create bunkerized-net
--- a/docs/quickstart_guide.md
+++ b/docs/quickstart_guide.md
@ -27,23 +27,244 @@ REVERSE_PROXY_HOST_2=http://app2.example.local:8080

 ### Docker

-TODO
+When using Docker, the recommended way is to create a network so bunkerized-nginx can communicate with the web service using its container name :
+```shell
+$ docker network create services-net
+$ docker run -d \
+         --name myservice \
+         --network services-net \
+         tutum/hello-world
+$ docker run -d \
+         --network services-net
+         -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 \
+         -e USE_REVERSE_PROXY=yes \
+         -e REVERSE_PROXY_URL=/ \
+         -e REVERSE_PROXY_HOST=http://myservice \
+         bunkerity/bunkerized-nginx
+```
+
+docker-compose equivalent :
+```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
+      - USE_REVERSE_PROXY=yes
+      - REVERSE_PROXY_URL=/
+      - REVERSE_PROXY_HOST=http://myservice
+    networks:
+      - services-net
+    depends_on:
+      - myservice
+
+  myservice:
+    image: tutum/hello-world
+    networks:
+      - services-net
+
+networks:
+  services-net:
+```

 ### Docker autoconf

-TODO
+When the Docker autoconf stack is running, you simply need to start the container hosting your web service and add the environment variables as labels :
+```shell
+$ docker run -d \
+         --name myservice \
+         --network services-net \
+         -l bunkerized-nginx.SERVER_NAME=www.example.com \ 
+         -l bunkerized-nginx.USE_REVERSE_PROXY=yes \
+         -l bunkerized-nginx.REVERSE_PROXY_URL=/ \
+         -l bunkerized-nginx.REVERSE_PROXY_HOST=http://myservice \
+         tutum/hello-world
+```
+
+docker-compose equivalent :
+```yaml
+version: '3'
+
+services:
+
+  myservice:
+    image: tutum/hello-world
+    networks:
+      myservice:
+        aliases:
+          - myservice
+    labels:
+      - bunkerized-nginx.SERVER_NAME=www.example.com
+      - bunkerized-nginx.USE_REVERSE_PROXY=yes
+      - bunkerized-nginx.REVERSE_PROXY_URL=/
+      - bunkerized-nginx.REVERSE_PROXY_HOST=http://myservice
+
+networks:
+  services-net:
+    external:
+      name: services-net
+```

 ### Docker Swarm

-TODO
+When the Docker Swarm stack is running, you simply need to start the Swarm service hosting your web service and add the environment variables as labels :
+```shell
+$ docker service create \
+         --name myservice \
+         --network services-net \
+         -l bunkerized-nginx.SERVER_NAME=www.example.com \ 
+         -l bunkerized-nginx.USE_REVERSE_PROXY=yes \
+         -l bunkerized-nginx.REVERSE_PROXY_URL=/ \
+         -l bunkerized-nginx.REVERSE_PROXY_HOST=http://myservice \
+         tutum/hello-world
+```
+
+docker-compose equivalent :
+```yaml
+version: '3'
+
+services:
+
+  myservice:
+    image: tutum/hello-world
+    networks:
+      myservice:
+        aliases:
+          - myservice
+    deploy:
+      placement:
+        constraints:
+          - "node.role==worker"
+      labels:
+        - bunkerized-nginx.SERVER_NAME=www.example.com
+        - bunkerized-nginx.USE_REVERSE_PROXY=yes
+        - bunkerized-nginx.REVERSE_PROXY_URL=/
+        - bunkerized-nginx.REVERSE_PROXY_HOST=http://myservice
+
+networks:
+  services-net:
+    external:
+      name: services-net
+```

 ### Kubernetes

-TODO
+Example deployment and service declaration :
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: myservice
+  labels:
+    app: myservice
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: myservice
+  template:
+    metadata:
+      labels:
+        app: myservice
+    spec:
+      containers:
+      - name: myservice
+        image: tutum/hello-world
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: myservice
+spec:
+  type: ClusterIP
+  selector:
+    app: myservice
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 80
+```
+
+The most straightforward way to add a reverse proxy in the Kubernetes cluster is to declare it in the Ingress resource :
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: bunkerized-nginx-ingress
+  # this label is mandatory
+  labels:
+    bunkerized-nginx: "yes"
+spec:
+  tls:
+  - hosts:
+    - www.example.com
+  rules:
+  - host: "www.example.com"
+    http:
+      paths:
+      - pathType: Prefix
+        path: "/"
+        backend:
+          service:
+            name: myservice
+            port:
+              number: 80
+```
+
+An alternative "hackish" way is to use environment variables as annotations prefixed with "bunkerized-nginx." inside the Service resource of your web service :
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: myservice
+  # this label is mandatory
+  labels:
+    bunkerized-nginx: "yes"
+  annotations:
+    bunkerized-nginx.SERVER_NAME: "www.example.com"
+    bunkerized-nginx.USE_REVERSE_PROXY: "yes"
+    bunkerized-nginx.REVERSE_PROXY_URL: "/"
+    bunkerized-nginx.REVERSE_PROXY_HOST: "http://myservice"
+spec:
+  type: ClusterIP
+  selector:
+    app: myservice
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 80
+```

 ### Linux

-TODO
+Example of a basic configuration file :
+```conf
+HTTP_PORT=80
+HTTPS_PORT=443
+SERVER_NAME=www.example.com
+AUTO_LETS_ENCRYPT=yes
+USE_REVERSE_PROXY=yes
+REVERSE_PROXY_URL=/
+# Local proxied application
+REVERSE_PROXY_HOST=http://127.0.0.1:8080
+# Remote proxied application
+#REVERSE_PROXY_HOST=http://service.example.local:8080
+```

 ## PHP applications

@ -69,12 +290,20 @@ LOCAL_PHP_PATH=/opt/bunkerized-nginx/www

 ### Docker

+TODO
+
 ### Docker autoconf

+TODO
+
 ### Docker Swarm

+TODO
+
 ### Kubernetes

+TODO
+
 ## Multisite

 If you have multiple services to protect, the easiest way to do it is by enabling the "multisite" mode. When using multisite, bunkerized-nginx will create one server block per server defined in the SERVER_NAME environment variable. You can configure each servers independently by adding the server name as a prefix.
@ -91,9 +320,16 @@ app2.example.com_REMOTE_PHP_PATH=/var/www/html

 ### Docker

+TODO
+
 ### Docker autoconf

+TODO
+
 ### Docker Swarm

+TODO
+
 ### Kubernetes

+TODO