https://github.com/ansibleguy/infra_nginx
Ansible Role to provision Nginx sites
https://github.com/ansibleguy/infra_nginx
ansible ansible-role automation certbot certificates iac infrastructure-as-code nginx webserver
Last synced: 4 months ago
JSON representation
Ansible Role to provision Nginx sites
- Host: GitHub
- URL: https://github.com/ansibleguy/infra_nginx
- Owner: ansibleguy
- License: other
- Created: 2021-10-05T20:27:27.000Z (over 3 years ago)
- Default Branch: latest
- Last Pushed: 2024-09-06T16:32:58.000Z (8 months ago)
- Last Synced: 2024-09-06T19:46:16.234Z (8 months ago)
- Topics: ansible, ansible-role, automation, certbot, certificates, iac, infrastructure-as-code, nginx, webserver
- Language: Jinja
- Homepage:
- Size: 179 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://nginx.org)
# Ansible Role - Nginx Webserver
Ansible Role to deploy one or multiple NGINX sites on a linux server.
[](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/molecule.sh.j2)
[](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/yamllint.sh.j2)
[](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/pylint.sh.j2)
[](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/ansiblelint.sh.j2)
[](https://galaxy.ansible.com/ui/standalone/roles/ansibleguy/infra_nginx)
Molecule Logs: [Short](https://badges.ansibleguy.net/log/molecule_infra_nginx_test_short.log), [Full](https://badges.ansibleguy.net/log/molecule_infra_nginx_test.log)
**Tested:**
* Debian 11
* Debian 12
----
## Install
```bash
# latest
ansible-galaxy role install git+https://github.com/ansibleguy/infra_nginx
# from galaxy
ansible-galaxy install infra_nginx
# or to custom role-path
ansible-galaxy install infra_nginx --roles-path ./roles
# install dependencies
ansible-galaxy install -r requirements.yml
# if you want to use basic-auth: install python dependencies
python3 -m pip install -r requirements.txt
```
----
## Advertisement
* Need **professional support** using Ansible or managing Web-Applications? Contact us:
E-Mail: [[email protected]](mailto:[email protected])
Tel: [+43 3115 40 900 0](tel:+433115409000)
Web: [EN](https://www.o-x-l.com) | [DE](https://www.oxl.at)
Language: German or English
* You want a simple **Ansible GUI**?
Check-out this [Ansible WebUI](https://github.com/ansibleguy/webui)
----
## Usage
### Config
Define the nginx dictionary as needed!
```yaml
nginx:
config:
client_max_body_size: '500m'
ssl_session_timeout: '15m'
sites:
some_proxy:
mode: 'proxy'
domain: 'some.guy.net'
aliases:
- 'service.guy.net'
port_ssl: 8443
port_plain: 8080
proxy: # default proxy-target is localhost
port: 50000 # target port
cache: # upstream content-caching
enable: true
ssl:
mode: 'existing' # pre-existing certificates to be copied to the target server
security:
# very basic filtering of bad bots based on user-agent matching
block_script_bots: true
block_bad_crawler_bots: true
guys_statics:
mode: 'server'
domain: 'static.guy.net'
serve:
path: '/var/www/static'
ssl:
mode: 'snakeoil'
config: # add settings as key-value pairs
LimitRequestFields: 10
config_additions: # add a list of custom lines of config
- 'location = /favicon.ico {alias /var/not_www/site_guys_statics/favicon.ico;}'
git_stuff:
mode: 'redirect'
redirect:
target: 'https://github.com/ansibleguy'
ssl:
mode: 'letsencrypt'
letsencrypt:
email: '[email protected]'
security:
restrict_methods: false
fileshare:
mode: 'server'
domain: 'files.guy.net'
serve:
path: '/var/www/files'
basic_auth:
enable: true
provider: 'file'
file:
users:
some_user: 'some_password'
```
### Execution
Run the playbook:
```bash
ansible-playbook -K -D -i inventory/hosts.yml playbook.yml
```
To only process a specific site: (_and safe time_)
```bash
ansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e only_site=SITE_NAME
# note: multiple comma-separated sites should also work
```
There are also some useful **tags** available:
* base => only configure basics; sites will not be touched
* sites
* config => only update site config (_excluding certificates_)
* certs
* letsencrypt
* auth
* only_certs (can be used as skip-tag)
To debug errors - you can set the 'debug' variable at runtime:
```bash
ansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e debug=yes
```
----
## Functionality
* **Package installation**
* Ansible dependencies (_minimal_)
* Nginx
* **Configuration**
* Support for multiple sites/servers
* Three **config-modes**:
* proxy (_default_)
* serve
* redirect
* Support for specific configurations using the 'config' and 'config_additions' parameters
* Option to filter 'locations' by GeoIP => COMING SOON (:
* **Default config**:
* Disabled: Generate self-signed ones
* **ca** => Generate a minimal Certificate Authority and certificate signed by it
* **letsencrypt** => Uses the LetsEncrypt certbot
* **existing** => Copy certificate files or use existing ones
* **Default opt-ins**:
* restricting methods to POST/GET/HEAD
* status-page listener on localhost
* Logging to syslog
* http2
* **Default opt-outs**:
* proxy-mode caching
* Blocking of Known Script-Bots
* Blocking of known Bad-Crawler-Bots
## Info
* **Note:** this role currently only supports debian-based systems
* **Note:** Most of the role's functionality can be opted in or out.
For all available options - see the default-config located in the main/site defaults-file!
* **Info:** Many variables can be set either on 'global' or 'per-site' scope.
Site config is always overruling the global one.
* **Note:** This role expects that the site's unencrypted 'server' will only redirect to its encrypted connection.
* **Note:** If you want all domain-names to get 'caught' by a site/server you need to add an underline '_' as alias or domain!
This will also be done automatically if no domain is supplied.
* **Warning:** Not every setting/variable you provide will be checked for validity. Bad config might break the role!
* **Info:** To disable default settings and headers => just set their value to: '' (_empty string_)
* **Info:** If you are filtering web-requests via GeoIP filter using your firewall => LetsEncrypt will work with only opening port 80 to the world.
Requests other than '.well-known/acme-challenge/' are just redirected to 443.
* **Info:** For LetsEncrypt renewal to work, you must allow outgoing connections to:
80/tcp, 443/tcp+udp to acme-v02.api.letsencrypt.org, staging-v02.api.letsencrypt.org (_debug mode_) and r3.o.lencr.org
* **Info:** This role also supports configuring basic-auth.
For advanced use-cases you might want to set [auth_request](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) in `site.config_additions_root` that can be used to implement OAuth-Proxies and so on.
* **Info:** You can set the `plain_only` flag to disable HTTPS. This might be nice-to-have if you are behind another proxy server.