ansible/ansible-role-nginx
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Patrick Jaroszewski
2026-06-24 17:29:12 -04:00
commit 72b96c06a4
15 changed files with 470 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+135
View File
@@ -0,0 +1,135 @@
# nginx (Ansible role)
Installs and configures nginx for **simple homelab / local-network** setups, where most
sites are "proxy a domain to a backend over HTTPS" and share a single wildcard cert.
This role exists because most of my nginx configs were nearly identical — same SSL
params, same proxy headers, same redirect-to-HTTPS pattern. The role captures that
shared shape, so each new service is a few lines of YAML instead of a copy-pasted
server block.
**Not for production.** No Let's Encrypt automation, no per-vhost cert provisioning,
no cleanup for sites removed from inventory, snakeoil cert as default. Override what
you need.
Tested on Debian (bookworm/trixie) and Ubuntu (jammy/noble).
---
## Quick start
```yaml
- hosts: nginx
become: true
roles:
- role: nginx
vars:
# Override the default snakeoil cert with your real one
nginx_ssl_certificate: /etc/nginx/ssl/lab.local/fullchain.pem
nginx_ssl_certificate_key: /etc/nginx/ssl/lab.local/privkey.pem
nginx_sites:
- name: default # keep the catch-all
template_path: site-configs/default.conf.j2
- name: vaultwarden # your service
domain_names:
- vault.lab.local
upstream_url: http://192.168.1.10:8080
```
That's it. `vault.lab.local` now serves over HTTPS, redirects plain HTTP → HTTPS,
uses the shared cert, and proxies everything to `192.168.1.10:8080`.
---
## Per-site options (`nginx_sites[*]`)
| Key | Type | Default | Notes |
|------------------------|----------|----------------------------------|-----------------------------------------------------------------------|
| `name` | string | **required** | Filename in `sites-available/`. |
| `domain_names` | list | **required** * | Values for `server_name`. |
| `upstream_url` | string | **required** * | `proxy_pass` target (e.g. `http://host:port`). |
| `ssl` | bool | `true` | Enable HTTPS listener + cert. |
| `allow_http` | bool | `false` | Also serve content over plain HTTP. By default HTTP → 301 → HTTPS. |
| `websockets` | bool | `false` | Include `websockets.conf` (upgrade headers). |
| `max_upload_size` | string | unset | `client_max_body_size` value, e.g. `"50m"`. |
| `extra_parameters` | string | unset | Freeform nginx directives injected into the server block. |
| `https_port` | int | `443` | Override HTTPS listen port. |
| `http_port` | int | `80` | Override HTTP listen port. |
| `ssl_certificate` | path | `nginx_ssl_certificate` | Per-site cert override. |
| `ssl_certificate_key` | path | `nginx_ssl_certificate_key` | Per-site key override. |
| `enabled` | bool | `nginx_site_enabled_by_default` | Create the `sites-enabled/` symlink. Setting `false` removes it. |
| `template_path` | string | `nginx_site_config_template` | Use a custom template (path relative to `templates/`). |
| `conf_file` | path | unset | Use a static file instead of the template (path relative to playbook).|
\* Required when using the built-in template. If you supply `conf_file` or a custom
`template_path`, only `name` is required.
---
## Role variables
| Variable | Default | Purpose |
|---------------------------------------|-----------------------------------------------|----------------------------------------------------------------------|
| `nginx_ssl_certificate` | `/etc/ssl/certs/ssl-cert-snakeoil.pem` | Default cert path for all sites. |
| `nginx_ssl_certificate_key` | `/etc/ssl/private/ssl-cert-snakeoil.key` | Default key path. |
| `nginx_resolver` | `127.0.0.53 valid=300s` | Global DNS resolver (used by OCSP stapling). Override for LAN DNS. |
| `nginx_resolver_timeout` | `5s` | |
| `nginx_site_enabled_by_default` | `true` | Whether sites without an explicit `enabled` get symlinked. |
| `nginx_delete_default_site_config` | `false` | Delete Debian's `sites-available/default` (only matters if you remove the `default` entry from `nginx_sites`). |
| `nginx_site_config_template` | `nginx-site.conf.j2` | Default template used when a site has no `template_path`/`conf_file`.|
| `nginx_sites` | one entry (the catch-all `default` site) | Your list of sites. |
| `nginx_snippets` | `[proxy-headers, ssl-params, websockets, fastcgi-php]` | Static snippets dropped into `/etc/nginx/snippets/`. |
| `nginx_conf_d_templates` | `[resolver.conf]` | Templated files rendered into `/etc/nginx/conf.d/`. |
Path variables (`nginx_site_config_path`, `nginx_site_enabled_path`,
`nginx_snippets_path`, `nginx_conf_d_path`) exist for completeness and default to
Debian's canonical locations. You usually shouldn't touch them.
---
## The default catch-all site
The shipped default entry (`name: default`) renders
`templates/site-configs/default.conf.j2`, which:
- Listens on `:80` with `default_server`, 301-redirects any unknown `Host:` to HTTPS.
- Listens on `:443 ssl http2` with `default_server`, returns `404`.
It exists so unknown-host traffic doesn't leak one of your real sites' certs/content
via SNI scans. Keep it if you have more than one site; remove it (and set
`nginx_delete_default_site_config: true`) if you have exactly one.
---
## Custom static configs
For sites that don't fit the template — e.g. a static file server, a non-proxy
site, an upstream block — write the full nginx config yourself and point at it:
```yaml
- name: media
conf_file: site-configs/media.conf # path relative to your playbook
```
The role copies it verbatim into `sites-available/`.
---
## Caveats
- **Snakeoil default cert.** The role works out of the box but presents an untrusted
self-signed cert. Set `nginx_ssl_certificate(_key)` to your real cert before
serving anything real.
- **One shared cert by default.** A single wildcard is the assumed homelab pattern.
Per-site override via `ssl_certificate` / `ssl_certificate_key` works for the
exceptions.
- **No removal cleanup.** If you delete a site from `nginx_sites`, the existing
`sites-available/<name>` and `sites-enabled/<name>` are not removed. Clean up
manually or set `enabled: false` and let the symlink task remove the link.
- **Debian/Ubuntu only.** Paths assume the Debian-style `sites-available/` +
`sites-enabled/` split. Won't work on Alpine, RHEL, etc. without surgery.
- **No Let's Encrypt / ACME.** Bring your own certs.
- **Resolver default assumes systemd-resolved.** Override `nginx_resolver` if you
use a different local resolver (e.g. `"dns.home valid=300s"`).
defaults/main.yaml
Executable
+38
View File
@@ -0,0 +1,38 @@
---
nginx_config_path: /etc/nginx
nginx_site_config_template: "nginx-site.conf.j2"
nginx_site_config_path: /etc/nginx/sites-available
nginx_site_enabled_path: /etc/nginx/sites-enabled
nginx_site_enabled_by_default: true
nginx_snippets_path: /etc/nginx/snippets
nginx_conf_d_path: /etc/nginx/conf.d
nginx_delete_default_site_config: false
nginx_site_config_extra_options: ""
# Default SSL cert used by all sites unless overridden per-site
# via item.ssl_certificate / item.ssl_certificate_key. Points at the
# Debian snakeoil cert (shipped by the ssl-cert package, an nginx dep)
# so the role works out of the box; override for real deployments.
nginx_ssl_certificate: /etc/ssl/certs/ssl-cert-snakeoil.pem
nginx_ssl_certificate_key: /etc/ssl/private/ssl-cert-snakeoil.key
# DNS resolver used by ssl_stapling and any proxy_pass with hostnames.
# Defaults to systemd-resolved's stub (present on modern Debian/Ubuntu).
# Override with your local resolver (e.g. "192.168.1.5 valid=300s").
nginx_resolver: "127.0.0.53 valid=300s"
nginx_resolver_timeout: "5s"
nginx_snippets:
- proxy-headers.conf
- ssl-params.conf
- websockets.conf
- fastcgi-php.conf
nginx_conf_d_templates:
- resolver.conf
nginx_sites:
- name: default
template_path: "site-configs/default.conf.j2"
files/nginx.conf
Executable
+58
View File
@@ -0,0 +1,58 @@
user www-data;
worker_processes auto;
pid /run/nginx.pid;
error_log /var/log/nginx/error.log;
include /etc/nginx/modules-enabled/*.conf;
events {
worker_connections 768;
# multi_accept on;
}
http {
##
# Basic Settings
##
sendfile on;
tcp_nopush on;
types_hash_max_size 2048;
# server_tokens off;
server_names_hash_max_size 768;
server_names_hash_bucket_size 96;
# server_name_in_redirect off;
include /etc/nginx/mime.types;
default_type application/octet-stream;
##
# Logging Settings
##
access_log /var/log/nginx/access.log;
##
# Gzip Settings
##
gzip on;
# gzip_vary on;
# gzip_proxied any;
# gzip_comp_level 6;
# gzip_buffers 16 8k;
# gzip_http_version 1.1;
# gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
##
# Virtual Host Configs
##
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
}
files/snippets/fastcgi-php.conf
Executable
+13
View File
@@ -0,0 +1,13 @@
# regex to split $uri to $fastcgi_script_name and $fastcgi_path
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
# Check that the PHP script exists before passing it
try_files $fastcgi_script_name =404;
# Bypass the fact that try_files resets $fastcgi_path_info
# see: http://trac.nginx.org/nginx/ticket/321
set $path_info $fastcgi_path_info;
fastcgi_param PATH_INFO $path_info;
fastcgi_index index.php;
include fastcgi.conf;
files/snippets/proxy-headers.conf
Executable
+5
View File
@@ -0,0 +1,5 @@
# /etc/nginx/snippets/proxy-headers.conf
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
files/snippets/ssl-params.conf
+10
View File
@@ -0,0 +1,10 @@
# /etc/nginx/snippets/ssl-params.conf
# Shared TLS parameters. Cert paths live with the site, not here.
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers EECDH+AESGCM:EDH+AESGCM;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
ssl_stapling on;
ssl_stapling_verify on;
files/snippets/websockets.conf
Executable
+6
View File
@@ -0,0 +1,6 @@
# /etc/nginx/snippets/websockets.conf
# enable websockets: http://nginx.org/en/docs/http/websocket.html
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_redirect off;
handlers/main.yaml
Executable
+11
View File
@@ -0,0 +1,11 @@
---
- name: Validate nginx configuration
ansible.builtin.command: nginx -t
changed_when: false
become: true
- name: Reload nginx
ansible.builtin.service:
name: nginx
state: reloaded
become: true
meta/main.yaml
+24
View File
@@ -0,0 +1,24 @@
---
galaxy_info:
role_name: nginx
author: Patrick Jaroszewski
description: Installs and configures nginx with templated site configs
license: MIT
min_ansible_version: "2.14"
platforms:
- name: Debian
versions:
- bullseye
- bookworm
- trixie
- name: Ubuntu
versions:
- jammy
- noble
galaxy_tags:
- nginx
- web
- proxy
- tls
dependencies: []
tasks/configure_nginx.yaml
Executable
+76
View File
@@ -0,0 +1,76 @@
---
- name: Delete default nginx site configuration
ansible.builtin.file:
path: "{{ nginx_site_config_path }}/default"
state: absent
when: nginx_delete_default_site_config
notify:
- Validate nginx configuration
- Reload nginx
- name: Add all the template site configurations
ansible.builtin.template:
src: "{{ item.template_path | default(nginx_site_config_template) }}"
dest: "{{ nginx_site_config_path }}/{{ item.name }}"
owner: root
mode: "0644"
when: item.conf_file is undefined
loop: "{{ nginx_sites }}"
notify:
- Validate nginx configuration
- Reload nginx
- name: Add all site configs using custom files
ansible.builtin.copy:
src: "{{ item.conf_file }}"
dest: "{{ nginx_site_config_path }}/{{ item.name }}"
owner: root
mode: "0644"
when: item.conf_file is defined
loop: "{{ nginx_sites }}"
notify:
- Validate nginx configuration
- Reload nginx
- name: Manage symlinks for sites
ansible.builtin.file:
src: "{{ nginx_site_config_path }}/{{ item.name }}"
dest: "{{ nginx_site_enabled_path }}/{{ item.name }}"
state: "{{ (item.enabled | default(nginx_site_enabled_by_default)) | ternary('link', 'absent') }}"
loop: "{{ nginx_sites }}"
notify:
- Validate nginx configuration
- Reload nginx
- name: Copy over configuration snippets
ansible.builtin.copy:
src: "snippets/{{ item }}"
dest: "{{ nginx_snippets_path }}/{{ item }}"
owner: root
mode: "0644"
loop: "{{ nginx_snippets }}"
notify:
- Validate nginx configuration
- Reload nginx
- name: Render templated conf.d files
ansible.builtin.template:
src: "conf.d/{{ item }}.j2"
dest: "{{ nginx_conf_d_path }}/{{ item }}"
owner: root
mode: "0644"
loop: "{{ nginx_conf_d_templates }}"
notify:
- Validate nginx configuration
- Reload nginx
- name: Add the main nginx configuration
ansible.builtin.copy:
src: nginx.conf
dest: /etc/nginx/nginx.conf
owner: root
mode: "0644"
validate: 'nginx -t -c %s'
notify:
- Validate nginx configuration
- Reload nginx
tasks/install_nginx.yaml
Executable
+7
View File
@@ -0,0 +1,7 @@
---
- name: Install NGINX
ansible.builtin.apt:
name: nginx
state: present
update_cache: true
cache_valid_time: 3600
tasks/main.yaml
Executable
+3
View File
@@ -0,0 +1,3 @@
---
- ansible.builtin.include_tasks: install_nginx.yaml
- ansible.builtin.include_tasks: configure_nginx.yaml
templates/conf.d/resolver.conf.j2
+4
View File
@@ -0,0 +1,4 @@
# /etc/nginx/conf.d/resolver.conf
# Global DNS resolver for runtime lookups (OCSP stapling, runtime proxy_pass).
resolver {{ nginx_resolver }};
resolver_timeout {{ nginx_resolver_timeout }};
templates/nginx-site.conf.j2
Executable
+60
View File
@@ -0,0 +1,60 @@
{%- if (item.ssl | default(true)) and not (item.allow_http | default(false)) %}
server {
listen {{ item.http_port | default(80) }};
listen [::]:{{ item.http_port | default(80) }};
server_name{% for domain_name in item.domain_names %} {{ domain_name }}{% endfor %};
return 301 https://$host$request_uri;
}
{% endif -%}
server {
{%- if item.ssl | default(true) %}
listen {{ item.https_port | default(443) }} ssl http2;
listen [::]:{{ item.https_port | default(443) }} ssl http2;
{%- if item.allow_http | default(false) %}
listen {{ item.http_port | default(80) }};
listen [::]:{{ item.http_port | default(80) }};
{%- endif %}
{%- else %}
listen {{ item.http_port | default(80) }};
listen [::]:{{ item.http_port | default(80) }};
{%- endif %}
server_name{% for domain_name in item.domain_names %} {{ domain_name }}{% endfor %};
# Set proxy headers
include {{ nginx_snippets_path }}/proxy-headers.conf;
{%- if item.ssl | default(true) %}
# SSL certificate and parameters
ssl_certificate {{ item.ssl_certificate | default(nginx_ssl_certificate) }};
ssl_certificate_key {{ item.ssl_certificate_key | default(nginx_ssl_certificate_key) }};
include {{ nginx_snippets_path }}/ssl-params.conf;
{%- endif %}
{%- if item.websockets | default(false) %}
# Enable websockets
include {{ nginx_snippets_path }}/websockets.conf;
{%- endif %}
{%- if item.max_upload_size | default(false) %}
# Max upload size
client_max_body_size {{ item.max_upload_size }};
{%- endif %}
{%- if item.extra_parameters | default(false) %}
{{ item.extra_parameters }}
{%- endif %}
location / {
proxy_pass {{ item.upstream_url }};
}
}
templates/site-configs/default.conf.j2
+20
View File
@@ -0,0 +1,20 @@
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
# Redirect all HTTP requests to HTTPS via a 301 response
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2 default_server;
listen [::]:443 ssl http2 default_server;
server_name _;
ssl_certificate {{ nginx_ssl_certificate }};
ssl_certificate_key {{ nginx_ssl_certificate_key }};
include {{ nginx_snippets_path }}/ssl-params.conf;
return 404;
}