Nginx for Debian/FreeBSD Ansible Role

This role installs and configures Nginx on Debian and FreeBSD.

Features:

• Strong SSL/TLS support
• Manage basic authentication on sites/locations
• Proxy and Upstream support
• Quick PHP setup
• Preconfigured site templates (compatible with many applications)
• Automatic HTTP2 configuration for SSL/TLS sites
• Manage dynamic modules (installation and loading)
• Deploy custom site configurations
• Supports proxy protocol
• Generates certificates using acme.sh (Let's Encrypt) – EXPERIMENTAL

Supported Operating Systems:

OS	Working	Stable (active support)
Debian Jessie (8)	Yes	Check latest supported version (1.5.0)
Debian Stretch (9)	Yes	Check latest supported version (1.9.0)
Debian Buster (10)	Yes	Yes
Debian Bullseye (11)	Yes	Yes
Debian Bookworm (12)	Yes	Not yet :)
FreeBSD 11	NA	No
FreeBSD 12	NA	No
Ubuntu 20.04	Yes	Yes
Ubuntu 22.04	Yes	Yes

Requirements

• Ansible version 2.11 or higher
• If you enable nginx_backports, make sure to install the backports repository before using this role.

Role Variables

For Packaging

Debian:

• nginx_apt_package: APT package for Nginx (try: apt-cache search ^nginx)
• nginx_backports: Boolean to install Nginx from the backports repository

FreeBSD:

• nginx_pkgng_package: PKGNG package for Nginx (should be "nginx" or "nginx-devel")

Shared Variables

• nginx_root: Root directory for your files
• nginx_log_dir: Directory for logs (remember to update logrotate config if changed)
• nginx_resolver: List of DNS resolvers (defaults to OpenDNS)
• nginx_error_log_level: Default log level
• nginx_auto_config_httpv2: Automatically configure HTTP2 where supported
• nginx_fastcgi_fix_realpath: Use realpath for FastCGI (fixes issues with symlinks and PHP opcache)
• nginx_default_hsts: Default header sent for HSTS

Nginx Configuration

• nginx_user
• nginx_worker_processes
• nginx_pid: Daemon PID file
• nginx_events_*: Variables in the events block
• nginx_http_*: Variables in the HTTP block
• nginx_custom_core: Instructions for the core (will be added to /etc/nginx/nginx.conf)
• nginx_custom_http: Instructions (will be added to /etc/nginx/conf.d/custom.conf)
• nginx_module_packages: List of module packages to install (Debian)
• nginx_load_modules: List of modules to load (full path), use only on FreeBSD

Miscellaneous

• nginx_debug_role: Set to true to see output from tasks without logs

About Modules

The latest updates from Debian backports load modules from the /etc/nginx/modules-enabled directory. Disabling/enabling is no longer supported. Please wait for further updates.

Configuration Guides

Site configuration

PHP configuration

Upstream Configuration

SSL/TLS Configuration

Basic Auth

FreeBSD

acme.sh

Note

• Active support is available for Debian/Ubuntu.
• FreeBSD support is experimental; currently tested on version 10.2 (but may work on others).

Dependencies

See: requirements.yml.

If You Need to Develop This Role Locally on Vagrant

Before using Vagrant, run this command once:

ansible-galaxy install -p ./tests/ HanXHX.php,master

If You Need to Develop This Role Locally with Molecule

Check available scenarios in the molecule directory.

For the debian-12 scenario:

molecule -v -c molecule/_shared/base.yml verify -s debian-12

Example Playbook

See tests/test.yml.

License

GPLv2

Donation

If this code has helped you or you’ve used it for your projects, feel free to show appreciation with a drink! :beers:

• Bitcoin: 1BQwhBeszzWbUTyK4aUyq3SRg7rBSHcEQn
• Ethereum: 63abe6b2648fd892816d87a31e3d9d4365a737b5
• Litecoin: LeNDw34zQLX84VvhCGADNvHMEgb5QyFXyD
• Monero: 45wbf7VdQAZS5EWUrPhen7Wo4hy7Pa7c7ZBdaWQSRowtd3CZ5vpVw5nTPphTuqVQrnYZC72FXDYyfP31uJmfSQ6qRXFy3bQ

No cryptocurrency? A ⭐️ on the project is also a great way to say thank you! :sunglasses:

Author Information

• Twitter: @hanxhx_