Doc split + SSL + minor changes

doc/auth.md

@@ -0,0 +1,41 @@
+Auth Basic management
+=====================
+
+Description
+-----------
+
+Auth basic is managed in a separate list. Each auth file can be shared between locations or vhosts.
+
+Each htpasswd has few keys:
+
+- `name`: (M) used to create file and as pointee
+- `description`: (M) Used for the message box :)
+- `users`: each users is composed with 3 keys: `name` (M), `password` (M) and `state` present/absent (default: present)
+- `state`: (O) present or absent. Default: present
+
+`nginx_htpasswd` should be placed in a vaut file.
+
+Exemple
+-------
+
+```
+nginx_vhosts:
+# htpasswd on all vhost
+  - name: test.local
+    htpasswd: 'hello'    
+    template: '_base'
+
+# htpasswd only in /hello
+  - name: test-location.local
+    template: '_base'
+    location:
+      '/hello':
+        - htpasswd: 'hello'    
+
+nginx_htpasswd:
+  - name: 'hello'
+    description: 'Please login!'
+    users:
+      - name: 'bob'
+        password: 'my_pass'
+```

doc/php.md

@@ -0,0 +1,17 @@
+PHP
+===
+
+- `nginx_php`: boolean if you need to preconfigure PHP (default: false)
+- `nginx_php_sockets`: list of sockets (see bellow)
+
+You should see [Nginx upstream module doc](http://nginx.org/en/docs/http/ngx_http_upstream_module.html).
+
+Each socket have:
+
+- `unix_socket`
+- `host`
+- `port`
+- `weight`
+- `max_fails`
+- `fail_timeout`
+

doc/ssl.md

@@ -0,0 +1,52 @@
+SSL/TLS Management
+==================
+
+You can put all this variables in a separated vault file.
+
+Variables
+---------
+
+- `nginx_dh`: DH content
+- `nginx_dh_length`: DH key length (default is 2048)
+- `nginx_dh_path`: file localation
+- `nginx_ssl_dir`: directory where you install your SSL/TLS keys
+- `nginx_ssl_pairs`
+
+Cert/Key pairs
+--------------
+
+This list have 3 mandatory keys:
+
+- `name`: MUST be unique 
+- `key`: content of the private key
+- `cert`: content of the public key
+
+Note: `name` is used to deploy key/cert. With defaults values dans `name` = "foo", key is -> /etc/nginx/ssl/foo/foo.key
+
+Diffie-Hellman
+--------------
+
+If you do not specify any dh param, this role auto generates it.
+
+Example
+-------
+
+```
+nginx_vhosts;
+  - name: 'test-ssl.local'
+    proto: ['http', 'https']
+    template: '_base'
+    ssl_name: 'mysuperkey'
+
+nginx_ssl_pairs:
+  - name: mysuperkey
+    key: |
+      -----BEGIN RSA PRIVATE KEY-----
+      ....(snip)....
+      -----END RSA PRIVATE KEY-----
+    cert: |
+      -----BEGIN CERTIFICATE-----
+      ....(snip)....
+      -----END CERTIFICATE-----
+```
+

doc/upstream.md

@@ -0,0 +1,29 @@
+Upstream management
+===================
+
+`nginx_upstreams`: List of dict. An upstream has few keys. See bellow.
+
+Note: Few params are unavailable on old Nginx version. But this role do _not_ put it if your version is too old!
+
+Upstream params
+---------------
+
+- `name`: upstream name. Can be use in vhost with *proxy_pass http://upstream_name*
+- `params`: list of param (hash, zone...)
+- `servers`: each upstream MUST have at least 1 server
+
+Server params
+-------------
+
+You must set a `path`. For example: *192.168.0.50:8080* or *unix:/tmp/my.sock*.
+
+All this params are optional. You should see [Nginx upstream doc](http://nginx.org/en/docs/http/ngx_http_upstream_module.html).
+
+- `weight`
+- `max_fails`
+- `fail_timeout`
+- `backup`
+- `down`
+- `route`
+- `slow`start`
+

doc/vhost.md

@@ -0,0 +1,55 @@
+Vhost management
+================
+
+You can see many examples in: [tests/test.yml](../tests/test.yml).
+
+`nginx_vhosts`: List of dict. A vhost has few keys. See bellow.
+
+Common
+------
+
+  - `name`: (M) Domain or list of domain used.
+  - `template`: (D) template used to create vhost. Optional if you set `delete` to true or using `redirect_tor`.
+  - `enable`: (O) Enable the vhost (default is true)
+  - `delete`: (O) Delete the vhost (default is false)
+  - `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).
+  - `redirect_to_code`: Redirect code (default: 302)
+  - `location`: (O) Add new custom locations (it does not overwrite!)
+  - `more`: (O) Add more custom infos.
+  - `upstream_params`: (O) Add upstream params (useful when you want to pass variables to PHP)
+  - `override_try_files`: (O) overrides default try\_files defined in template
+  - `manage_local_content`: (O) Boolean. Set to false if you do not want to manage local content (images, css...). This option is useless if you use `_proxy` template or `redirect_to` feature.
+  - `htpasswd`: (0) References name key in `nginx_htpasswd`. Enable auth basic on all vhost.
+
+(O): Optional
+(M): Mandatory
+(D): Depends other keys...
+
+Templates
+---------
+
+  - `_base`: static template
+  - `_backuppc`: access to [BackupPC](http://backuppc.sourceforge.net/) (be careful: you need to install [fcgiwrap](https://packages.debian.org/jessie/fcgiwrap))
+  - `_dokuwiki`
+  - `_redirect`: should not be called explicitly
+  - `_phalcon`: Phalcon PHP Framework
+  - `_php`: PHP base template. Can work with many frameworks/tools
+  - `_php_index`: Same as above. But you can only run index.php
+  - `_proxy`
+  - `_wordpress`
+
+Templates works as parent-child.
+
+About proxy template
+--------------------
+
+Proxy template allow you to use Nginx as reverse proxy. Usefull when you have an application service such as Redmine, Jenkins...
+
+You have many key added to vhost key:
+
+  - `upstream_name`: (O) upstream name used to pass proxy
+  - `proxy_params`: (M) list of raw params passed to the vhost
+
+(O) : Optional
+