ansible-nginx/doc/site.md

142 lines
4.6 KiB
Markdown
Raw Normal View History

Site management
===============
2016-01-12 18:14:36 +07:00
You can see many examples in: [tests/test.yml](../tests/test.yml).
`nginx_sites`: List of dict. A site has few keys. See bellow.
2016-01-12 18:14:36 +07:00
Common
------
2016-01-12 20:48:53 +07:00
- `name`: (M) Domain or list of domain used.
- `state`: (O) Site status. Can be "present" (default), "absent" and "disabled".
2020-08-23 23:10:34 +07:00
- `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`.
2016-01-12 20:48:53 +07:00
- `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).
2016-01-12 20:48:53 +07:00
- `redirect_to_code`: Redirect code (default: 302)
2020-08-23 23:10:34 +07:00
- `redirect_https`: (O) Boolean. Redirect HTTP to HTTPS. If "true", you _MUST_ set `proto` to `['https']`.
2016-01-12 20:48:53 +07:00
- `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)).
2019-02-20 21:13:25 +07:00
- `location_before`: (O) Add new custom locations before generated location by template
- `location_order_before`: (O) Manages location order for `location_before`
2016-01-12 20:48:53 +07:00
- `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`: (O) References name key in `nginx_htpasswd`. Enable auth basic on all site. Set "false" to disable.
2016-01-12 20:48:53 +07:00
- `proto`: (O) list of protocol used. Default is a list with "http". If you need http and https, you must set a list with "http" and "https". You can only set "https" without http support.
2016-11-07 23:22:14 +07:00
- `ssl_name`: (D) name of the key used when using TLS/SSL. Optional when `proto` contains "https". If you don't set this value, it will search by `name`.
- `ssl_template` (O) "strong" (default) or "legacy". You can disable SSL helpers and add your own directives by setting "false".
- `listen_proxy_protocol` (O) Enable proxy protocol on http port.
- `listen_proxy_protocol_ssl` (O) Enable proxy protocol on https port.
- `hsts` (O) overwrite default header for hsts
2016-01-12 18:14:36 +07:00
2020-08-23 23:10:34 +07:00
### Templates
2016-01-12 18:14:36 +07:00
2016-01-12 20:48:53 +07:00
- `_base`: static template
- `_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`
2016-01-12 18:14:36 +07:00
Templates works as parent-child.
2020-08-23 23:10:34 +07:00
### About proxy template
2016-01-12 18:14:36 +07:00
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 site key:
2016-01-12 18:14:36 +07:00
2016-01-12 20:48:53 +07:00
- `upstream_name`: (O) upstream name used to pass proxy
- `proxy_params`: (M) list of raw params passed to the site
2016-01-12 18:14:36 +07:00
(O) : Optional
2020-08-23 23:10:34 +07:00
### Default sites
2016-01-21 23:08:01 +07:00
You can manage default site by setting domain name to these variables.
2016-01-21 23:08:01 +07:00
- `nginx_default_site`
- `nginx_default_site_ssl`
2020-08-23 23:10:34 +07:00
*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;
}
}
```