From 40ebe61c57f97a09664ad851d618aed42e4fc443 Mon Sep 17 00:00:00 2001
From: Emilien Mantel <emilien.mantel@gmail.com>
Date: Sun, 23 Aug 2020 18:10:34 +0200
Subject: [PATCH] Add doc for custom site templates

---
 doc/site.md | 95 +++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 82 insertions(+), 13 deletions(-)

diff --git a/doc/site.md b/doc/site.md
index c3fb834..8f8c940 100644
--- a/doc/site.md
+++ b/doc/site.md
@@ -9,14 +9,30 @@ Common
 ------
 
 - `name`: (M) Domain or list of domain used.
-- `template`: (D) template used to create site. Optional if you set `state`=`absent` or using `redirect_to`.
-- `filename`: (O) Specify filename in /etc/nginx/sites-*. Do NOT specify default (reserved keyword). It will be used for log filenames and directories creation.
 - `state`: (O) Site status. Can be "present" (default), "absent" and "disabled".
+- `filename`: (O) Specify filename in `/etc/nginx/sites-*`. Do NOT specify default (reserved keyword). It will be used for log filenames and directories creation.
+
+(O): Optional
+(M): Mandatory
+(D): Depends other keys...
+
+You can use 2 config (at the same time time):
+
+- pre-built: Some configuration are templated (Wordpress, Symfony...), auto create root dir, perform an "A+" on ssllabs for https... etc
+- custom: Push your own site config template. Usefull when you have a complex configuration.
+
+
+Pre-built site config
+---------------------
+
+# Keys
+
+- `template`: (M) template used to create site. Optional if you set `state`=`absent` or using `redirect_to`.
 - `redirect_from`: (O) Domain list to redirect to the first `name`. You can use this key to redirect non-www to www
 - `redirect_to`: (O) Redirect all requests to this domain. Please set scheme (http:// or https:// or $sheme).
 - `headers`: (O) Set additionals header as key/value list. You can append "always" to the value. Show [nginx doc](http://nginx.org/en/docs/http/ngx_http_headers_module.html).
 - `redirect_to_code`: Redirect code (default: 302)
-- `redirect_https`: (O) Boolean. Redirect HTTP to HTTPS. If "true", you _MUST_ set `proto` to ```['https']```.
+- `redirect_https`: (O) Boolean. Redirect HTTP to HTTPS. If "true", you _MUST_ set `proto` to `['https']`.
 - `location`: (O) Add new custom locations (it does not overwrite!)
 - `location_order`: (O) Due to non preditive `location` order, you can provide the good order (see test-location.local in [tests/test.yml](../tests/test.yml)).
 - `location_before`: (O) Add new custom locations before generated location by template
@@ -33,12 +49,7 @@ Common
 - `listen_proxy_protocol_ssl` (O) Enable proxy protocol on https port.
 - `hsts` (O) overwrite default header for hsts
 
-(O): Optional
-(M): Mandatory
-(D): Depends other keys...
-
-Templates
----------
+### Templates
 
 - `_base`: static template
 - `_dokuwiki`
@@ -51,8 +62,7 @@ Templates
 
 Templates works as parent-child.
 
-About proxy template
---------------------
+### About proxy template
 
 Proxy template allow you to use Nginx as reverse proxy. Usefull when you have an application service such as Redmine, Jenkins...
 
@@ -63,10 +73,69 @@ You have many key added to site key:
 
 (O) : Optional
 
-Default sites
---------------
+### Default sites
 
 You can manage default site by setting domain name to these variables.
 
 - `nginx_default_site`
 - `nginx_default_site_ssl`
+
+*IT WORKS ONLY WITH PRE-BUIT SITES*
+
+
+### Example
+
+
+```yaml
+- nginx_sites:
+  - name: 'mywebsite.com'
+    template: '_wordpress'
+    headers:
+      x-ansibled: '1'
+    manage_local_content: false
+```
+
+
+Custom site config 
+------------------
+
+### Keys
+
+- `custom_template`: (M) template path used 
+
+You can add some extra infos if needed.
+
+### Example:
+
+```yaml
+- nginx_sites:
+  - name: 'mycustom-website.com'
+    custom_template: 'my/template_dir/the-template.conf.j2'
+    allow_admin: '192.168.0.0/24'
+```
+
+In `my/template_dir/the-template.conf.j2`:
+
+```
+#
+# {{ ansible_managed }} - {{ item.name }}
+#
+
+server {
+	listen 8080 http2 proxy_protocol;
+    server_name {{ item.name }};
+	index index.html;
+    root /var/www/{{ item.name }};
+
+	location / {
+		try_files $uri $uri/ =404;
+	}
+
+	location /admin {
+		allow {{ item.allow_admin }};
+		deny all;
+	}
+}
+```
+
+