Tools to configure a local development nginx setup to proxy our applications and services with SSL using mkcert.
This typically allows accessing servers via
service.local.dev-gutools.co.uk
, rather than a localhost:PORT
URL,
which among other things makes it possible to share cookies for the pan-domain authentication.
Installing and running dev-nginx will start an nginx server instance locally on your machine.
This instance will use any *.conf
files found locally within the directory /nginx/servers
to generate a virtual server host to proxy requests to localhost. You can locate this directory with the command dev-nginx locate
.
Each project config should include http directives for proxy localhost ports and necessary SSL certificates. This is quite repetitive, so dev-nginx
abstracts it away with the setup-app
and setup-cert
commands.
- The browser will make a request to a local development domain url, e.g.
service.local.dev-gutools.co.uk
- Request goes out to DNS where
*.local.dev-gutools.co.uk
is set to resolve back tolocalhost
(IP address:127.0.0.1
)- An alternative to using DNS is to add a new development url entry to
/etc/hosts
file resolving to 127.0.0.1. This can be done withdev-nginx add-to-hosts-file <DOMAIN>
.
- An alternative to using DNS is to add a new development url entry to
- Nginx server running locally receives the request
- Nginx server iterates over its virtual hosts, if it finds a
server_name
that matches the request, it will then proxy the request to the correct local project server instance.
brew tap guardian/homebrew-devtools
brew install guardian/devtools/dev-nginx
# update
brew upgrade dev-nginx
As listed in the Brewfile, dev-nginx
requires:
Once you have installed these dependencies, you can:
- Download the latest release
- Extract it
- Add the
bin
directory to your PATH.
For example:
wget -q https://github.com/guardian/dev-nginx/releases/latest/download/dev-nginx.tar.gz
mkdir -p dev-nginx && tar -xzf dev-nginx.tar.gz -C dev-nginx
export PATH="$PATH:$PWD/dev-nginx/bin"
dev-nginx
has a few commands available. Find them by passing no arguments:
$ dev-nginx
dev-nginx COMMAND <OPTIONS>
Available commands:
- add-to-hosts-file
- link-config
- locate
- restart
- setup-app
- setup-cert
- start
dev-nginx add-to-hosts-file
If it does not already exist, adds an entry to /etc/hosts
that resolves to 127.0.0.1
.
dev-nginx link-config /path/to/site.conf
Symlink an existing file into nginx configuration. You'll need to restart nginx to activate it (dev-nginx restart
).
dev-nginx locate
Locates the directory nginx is installed.
dev-nginx start
Starts nginx. Will fail if currently running. Add -g
to ignore if nginx is currently running.
dev-nginx restart
Stops, if running, and starts nginx.
dev-nginx setup-cert demo-frontend.foobar.co.uk
Uses mkcert
to issue a certificate for a domain, writing it to ~/.gu/mkcert
and symlinking it into the directory nginx is installed.
dev-nginx setup-app /path/to/nginx-mapping.yml
Generates config for nginx proxy site(s) from a config file, issues the certificate(s) and restarts nginx.
Your application's configuration is provided as a YAML file in the following format.
Example:
name: demo
domain-root: foobar.co.uk
mappings:
- port: 9001
prefix: demo-frontend
- port: 8800
prefix: demo-api
In general, the format is as follows:
name: <name of the project, used as its filename>
mappings: <list of server mappings>
ssl: <optional, defaults to `true` (you are unlikely to need to change this)>
domain-root: <optional, defaults to `local.dev-gutools.co.uk`>
Each mapping supports the following fields:
required
This is the domain prefix used for the service and will be prepended to the domain.
The default domain is local.dev-gutools.co.uk
but this can be overridden using the domain-root
key at the top level (to apply to all mappings) or in a mapping (to set the domain root for just that mapping).
required
This sets the port that will be proxied - i.e. the upstream backend service. These are commonly in the 9XXXs or 8XXXs.
This optionally sets the path for a websocket. If present, nginx will be configured to serve websocket traffic at that location.
Optionally instructs nginx to set a max body size on incoming requests.
The domain under which the service should run, which defaults to local.dev-gutools.co.uk
.
This can also be overriden for all mappings by specifying a domain-root
key at the top level.
You'll need to ensure your hosts file has entries for your new domains, so that they resolve:
127.0.0.1 demo-frontend.foobar.co.uk
127.0.0.1 demo-api.foobar.co.uk