Ease NGINX server administration with nginx-tools

nginx-tools is a command-line tool easing and automating the daily administration of a NGINX server on Debian. This howto describe its installation and usage.

This howto is tested on :

• Debian 10.0 Buster

Requirements

This howto requires :

• a NGINX HTTP server, as described by Install NGINX on Debian.

This howto recommends :

• biapy-updater, for automatic software updates.
• the installation of Let’s Encrypt client acme.sh, as described by Install (Let’s Encrypt) certbot client acme.sh on Debian.

Installation

Detect if sudo is available (“command” is used if not):

cmdProxy='command'
command type -f 'sudo' &>'/dev/null' && cmdProxy='sudo'

Install the tool :

${cmdProxy} wget "https://raw.githubusercontent.com/biapy/howto.biapy.com/master/nginx/nginx-tools" \
    --quiet --no-check-certificate --output-document="/usr/local/bin/nginx-tools"

Declare the downloaded file as executable:

${cmdProxy} chmod +x "/usr/local/bin/nginx-tools"

Automatic updates

Configure biapy-updater automatic updates to check for new versions of the software:

${cmdProxy} tee -a '/etc/biapy-updater.conf' <<< 'nginx-tools'

Usage examples

The details of the tool usage is given by :

command nginx-tools --help

Simple Virtual Host

Create a virtual host serving a folder :

sudo nginx-tools "www.domain.com" "/opt/www.domain.com"

Redirection

Create a virtual host redirecting a domain and all of its sub-domains to another web site:

sudo nginx-tools --template='redirect' \
        --alias="*.domain.com" \
        "domain.com" "http://www.domain.com/"

Reverse proxy

Create a virtual host serving a web site hosted on another server (by reverse proxy) :

sudo nginx-tools --template='reverse-proxy' \
        "www.domain.com" "http://domain.server.lan/"

For the reverse proxy to work, a VirtualHost named “www.domain.com” must be configured on the remote host (a.k.a. “domain.server.lan”).

If the remote host use Apache 2, it is recommended to apply the settings described by Get the real IP address of a visitor accessing to a Apache 2 server behind a reverse proxy.

Removal of a domain

Delete all virtual host for a domain:

sudo nginx-tools --remove "www.domain.com"

Secure host (HTTPS)

Any HTTPS host needs the creation of a valid SSL certificate for its domain name, as described by Create a SSL / TLS certificate on Debian or the use of acme.sh certbot (Let’s Encrypt) client.

Create a HTTPS virtual host with the –ssl=’auto’ option to automatically create a Let’s Encrypt certificate:

sudo nginx-tools --ssl='auto' 'www.domain.com' '/opt/www.domain.com'

Create a HTTPS virtual host with the –ssl option having for argument the name of the chosen SSL certificate (generally, the domain name of the web site), if you have an existing certificate :

sudo nginx-tools --ssl='www.domain.com' 'www.domain.com' '/opt/www.domain.com'

If the chosen certificate is a wildcard valid for all sub-domains, use:

sudo nginx-tools --ssl='*.domain.com' 'www.domain.com" '/opt/www.domain.com'

Note: Adding an argument to the –ssl option is equivalent to use these options:

sudo nginx-tools --ssl \
        --private-key="/etc/ssl/private/www.domain.com.key" \
        --public-key="/etc/ssl/certificates/www.domain.com.crt+chain+root" \
       'www.domain.com' '/opt/www.domain.com'