This repository has been archived. There will likely be no further development on the project and security vulnerabilities may be unaddressed.
NGINX Wrapper (nginx-wrapper) is a NGINX process wrapper written in go
that supports templating and plugins. Templating allows for modification
of nginx conf files before start up and on reload. Plugins allow for
integrating templating and events by hooking into nginx events such as
start up, reload and exit.
This is the tool for you, if want to run NGINX, but you don't want to create a sidecar, load a full init system, or write custom code in your container just to do:
- Templating
- Running another process
- Integrating with NGINX's reload life cycle
!WARNING!
THIS APPLICATION IS ALPHA AND STILL IN ACTIVE DEVELOPMENT
APIS MAY CHANGE AT ANY TIME
NGINX Wrapper can be thought of as a multipurpose tool that can be modified for your specific needs. The plugin interface and templating engine combine to allow for many simplifications of common application architectures.
- 12 Factor App
- Templating Based on External Configuration
- Plugins
- Agent Coprocess
- Service Discovery Integration
- Secret Store Integration
- Custom Authentication Services
- Service Mesh Proxy Integration
For a list of example configurations, see the Recipes Wiki.
You will need to have NGINX installed on the same system as nginx-wrapper.
NGINX 1.17.9 is the earliest version of NGINX that has been tested with
the wrapper. If the nginx binary is not in your PATH, then you will
need to specify the path to the binary in the configuration with
the nginx_binary setting.
Currently, nginx-wrapper has only been tested on Linux. However, it
may work on FreeBSD or Darwin (MacOS) because both platforms support
plugins. There is no plan for Windows support.
Copy the nginx-wrapper binary to your directory of choice.
Copy any plugins that you wish to use to a subdirectory ./plugins
relative to the nginx-wrapper binary or define a plugin directory
in your configuration.
Create a configuration file using a viper compatible format (JSON, TOML, YAML, HCL, envfile and Java properties formats). There are examples available for JSON, YAML, and TOML.
Create an nginx.conf.tmpl file in the working directory or create
a directory containing nginx.conf.tmpl and other templates. Then
specify that directories' path with the configuration parameter
conf_template_path. See the simple example
for how such a configuration may look.
For more detailed information on configuring NGINX Wrapper, refer to the configuration guide. For help with setting up template configuration, refer to the templating guide.
./nginx-wrapper help
NGINX Wrapper is a process wrapper that monitors NGINX for
(start, reload, and exit) events, provides a templating framework for
NGINX conf files and allows for plugins that extend its functionality.
Usage:
nginx-wrapper [flags]
nginx-wrapper [command]
Available Commands:
debug Display runtime configuration
help Help about any command
run run NGINX in a process wrapper
version Prints the nginx-wrapper version
Flags:
--config string path to configuration file (default "nginx-wrapper.toml")
-h, --help help for nginx-wrapper
Use "nginx-wrapper [command] --help" for more information about a command.
Run NGINX Wrapper's debug command to check your configuration
(replacing the sample config below with your own):
./nginx-wrapper debug --config sample_configs/nginx-wrapper-example.tomlYou should see the runtime configuration of NGINX Wrapper.
To start up NGINX via NGINX Wrapper (replacing the sample config below with your own):
./nginx-wrapper run --config sample_configs/nginx-wrapper-example.tomlThe NGINX Wrapper Development Guide has useful information on building and writing code for the wrapper.
Please refer to the Contributing Guidelines before doing a pull request.