README.md

iocage-plugin-nginx

An iocage plugin for nginx, a Robust and small WWW server.

CI
License

Table of Contents

• Installation
• Usage
  • Enabling TLS Mode with an SSL Certificate
  • Persisting Data
• Configuration
  • User Serviceable Configuration
  • nginx_mode
  • System Configuration
  • nginx_listen_addr
• Code of Conduct
• Issues
• Contributing
• Release History
• Authors
• License

Installation

This plugin can be installed via the fnichol/iocage-plugin-index plugin collection which is not installed on TrueOS or FreeBSD by default. For example, to install the plugin with a name of nginx and a dedicated IP address:

# Variables
jail=www
ip_addr=10.200.0.110

sudo iocage fetch \
  -g https://github.com/fnichol/iocage-plugin-index \
  -P nginx \
  --name $jail \
  ip4_addr="vnet0|$ip_addr"

Usage

Enabling TLS Mode with an SSL Certificate

To enable TLS you will need a public SSL certificate (i.e. a cert.pem file) and the private server key (i.e. a key.pem file) installed into the nginx configuration directory of the plugin's jail. Assuming a running installed plugin called www with a jail mount point of /mnt/tank/iocage/jails/www in the host system, the following will setup nginx to run under HTTPS:

# Variables
jail=www
jail_mnt=/mnt/tank/iocage/jails/$jail

cert=/tmp/cert.pem
key=/tmp/key.pem

sudo install -p -m 0644 $cert $jail_mnt/root/usr/local/etc/nginx/cert.pem
sudo install -p -m 0600 $key $jail_mnt/root/usr/local/etc/nginx/key.pem
sudo iocage exec $jail plugin config set nginx_mode https
sudo iocage exec $jail plugin services restart

Persisting Data

There is 1 primary directory that may contain data in an nginx jail:

• /usr/local/www/nginx The web site content served up by nginx

A good strategy is to create a ZFS dataset for this directory or use an existing dataset and mount it into the jail. This way, the jail can be destroyed and later re-created without losing the served up web content.

# Variables
jail=www
mnt=/mnt/tank/website

# Attach an existing ZFS dataset to be served
sudo iocage exec $jail rm -rf /usr/local/www/nginx
sudo iocage exec $jail mkdir /usr/local/www/nginx
sudo iocage fstab -a $jail "$mnt /usr/local/www/nginx nullfs ro 0 0"

# Restart the nginx service
sudo iocage exec $jail plugin services restart

Configuration

User Serviceable Configuration

The following configuration is intended to be modified by a plugin user.

nginx_mode

Whether or not TLS is being used for the service. See the TLS section for more information regarding how to install an SSL certificate.

• default: "http"
• valid values: "http"|"https"|"https-only"

Note that "https-" mode runs the service on HTTP and HTTPS whereas "https-only" mode only runs on HTTPS.

To change this value, use the installed plugin program and restart the services to apply the updated configuration:

plugin config set nginx_mode http
plugin services restart

System Configuration

The following configuration is used to configure and setup the services during post installation and is therefore not intended to be changed or modified by a plugin user.

nginx_listen_addr

Listen address for the service. (nginx reference)

• default: "0.0.0.0"

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to fnichol@nichol.ca.

Issues

If you have any problems with or questions about this project, please contact us through a GitHub issue.

Contributing

You are invited to contribute to new features, fixes, or updates, large or small; we are always thrilled to receive pull requests, and do our best to process them as fast as we can.

Before you start to code, we recommend discussing your plans through a GitHub issue, especially for more ambitious contributions. This gives other contributors a chance to point you in the right direction, give you feedback on your design, and help you find out if someone else is working on the same thing.

Release History

This project uses a "deployable main" strategy, meaning that the main branch is assumed to be working and production ready. As such there is no formal versioning process and therefore also no formal changelog documentation.

Authors

Created and maintained by Fletcher Nichol (fnichol@nichol.ca).

License

Licensed under the Mozilla Public License Version 2.0 (LICENSE.txt).

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the MPL-2.0 license, shall be licensed as above, without any additional terms or conditions.