Nginx Boilerplate
Awesome Nginx configuration template and a set of handy must-have snippets.
Features
- Expressive include-based config
- Optimized defaults
- Easy PHP integration
- Connections/requests rate limiting and throttling
- A-grade SSL setup
- FastCGI response caching
- Various predefined locations
- Advanced logging
- SEO
- Docker/Swarm ready
Requirements
Docker>=1.13docker-compose>=3.1
Configs themselves depend on Nginx >= 1.9.5, if used separately.
Usage
Abstract
Nginx boilerplate builds on top of official nginx and php alpine Docker images.
Additionally two basic docker-compose configs are provided: docker-compose.yml and docker-compose.override.yml.
The first contains the base/production version of the docker run config while the second transparently extends it to provide extra features for local development.
Only docker-compose.yml should be used in production.
docker-compose.override.yml also contains an empty php fpm installation for the sake of the demo. Also because the boilerplate assumes the usage of php-fpm and fails to start otherwise.
Check it out
You only need docker for this, simply run:
$ docker run --rm -it -p 80:80 -p 443:443 nginxboilerplate/nginx-boilerplate
Now open up https://localhost/go/home in your browser!
And since you only run the nginx part there, there's no support for php.
If you open the main page, which supposed to give you the phpinfo output, it's going to load for 10 secods and give you an error page.
Running it
For a quick and dirty localhost setup run:
$ docker-compose up -d
By default the bundled nginx image is provided with self-signed wildcard certificate for *.localhost, so you will have to instruct your browser to trust it.
Reloading
To not have to restart containers each time you modify your configs, you can simply run:
$ docker-compose exec nginx nginx -s reload
Logs
By default a new logs/ directory should be created in the project directory, that directly maps to the nginx logs directory.
Docker swarm
To run in Docker swarm first make sure your Docker setup is in swarm mode:
$ docker swarm init
First of all you need to define your domain ssl certificate and key as a swarm secret:
$ docker secret create cert.crt your_certificate.crt
$ docker secret create cert.key your_certificate_key.key
Now to start or update nginx (and php) services in the swarm run:
$ docker stack deploy -c docker-compose.yml --with-registry-auth --prune app
To see nginx logs run:
$ docker service logs -f app_nginx
To scale services:
$ docker service scale app_nginx=2 app_fpm=10
Now you can refresh the page a couple of times and notice different host names that your requests land on.
Customization
The main virtual host definition is located at servers/main.conf.
Probably the best way to work with the repo is by cloning it and hooking up docker hub to automatically build a new image whenever there's new code.
If something doesn't work
- Check error and access logs
- Create an issue on the project's github page