nginx-boilerplate / nginx-boilerplate

Awesome Nginx configuration template

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.13
• docker-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

nginx-boilerplate's Issues

(no-) www error?

Это такая фишка?
если указываю 188.226.169.238/ то перекидывает на http://www.188.226.169.238/

404

Hi!
Could yo be so kindly to help me? I have like this alias in my config. However, when I try to open link server.name/123/info.php then I have seen 404, nevertheless I can open server.name/123/info.txt. Where I should looking for error in config files?

location /123/ {
        alias /var/www/server.name/123/;
        autoindex off;
    }

Redirect loop when requesting an undefined/unmatched domain

Because of the always active www/no-www redirects if a client would make a request to some domain and nginx would not find a proper server definition to handle such request (matching server_name + listen pair) - it would cause a redirect loop.

www/no-www redirects work in such a way so that only one of those should trigger, automatically redirecting a request to the domain that is equal to server_name (with matching listen directive). If no such matching server definition would actually exist - client would end up being redirected from no-www to www infinitely.

What the hell? Strange log files in log dir.

Hello,

using nginx-bp for one site, today I opened log directory to check how the things are going. Noticed strange log files in log dir. What the?

Add crawl limit

http://habrahabr.ru/post/215233/

Разные php-fpm pool

Во-первых, спасибо за отличную работу. Всё очень хорошо структурировано.
Во-вторых есть вопрос. Я еще не очень разобрался с пулами php-fpm, но сейчас у меня есть 2 пула, один для тестов и второй для продакшена. Как мне указать какой использовать? Спасибо! Или просто использовать один пул?

PHP via php-fpm can not create cookies.

Hello, lost entire day today tracking down this thing.

Because of nginx-bp/enable/cache.conf php can't send cookies. PHP doesn't send even PHPSESSID cookie. Sessions are ignored.

Using PHP 5.5.6 +fpm, and nginx/1.4.4 on OS X 10.9.

Also /tmp/phpCache/ folder is empty, always.

I need your advice about cache.

I have this construction in host config.
if ($http_x_requested_with = XMLHttpRequest) { add_header Cache-Control "no-cache, must-revalidate, proxy-revalidate"; add_header X-Powered-By "Ajax avoid Cache"; }

However fastcgi_ignore_headers "Cache-Control" "Expires" "Set-Cookie"; ignoring instruction above.

In addition, I have timestamp like this ?time=1324234231342 in Ajax request. Nevertheless, fastcgi cached in any case.

What does it need to change for avoid cache?

enable/cache.conf causing phpmyadmin and session error

Not entirely certain why, but having this pulled in with my nginx config caused my phpmyadmin pages to give the error message:

"Cannot start session without errors, please check errors given in your PHP and/or webserver log file and configure your PHP installation properly."

Also it caused my Auto Logins on forums to stop working. Any thoughts on this?

I can not upload file =(

413 Request Entity Too Large
nginx

I want (in phpmyadmin) upload file crm.sql.bzip (568kb) and i see this error.

nano /etc/nginx/nginx-bp/limits/uploads.conf
client_max_body_size 100M;

прошу прощения за корявый английский )

404 error

I have switch ON for fastcgi_intercept_errors, however if I try look nonexistent file http://www.malenko.com/134.php I have seen 404 Nginx page.
If I try load nonexistent URL http://www.malenko.com/134 I have seen 404 page from Wordpress.

How make to show 404 page from Wordpress for any wrong URL i.e. 134.php|zip|doc|etc?

BR

static cache

"expires modified +7d;"

I think it's not good idea.
For example if i never will modify some image, browser will be taken it every time after one week.

client_max_body_size

You have duplicates of client_max_body_size.
In /system/http.conf and enable/uploads.conf.
You should eliminate one them.

no port in upstream "php"

Не могу понять, отчего nginx ругается.
[emerg] 2465#0: no port in upstream "php" in /etc/nginx/nginx-bp/enable/php.conf

Change boilerplate structure

Have you thought about changing boilerplate directory structure? It would be great to leave in this repository only content inside nginx-bp (move everything from nginx-bp to repository root).

This way we could just clone from nginx config directory and in our nginx.conf include interested configs.

The way I work now is: clone, get inside src directory copy nginx-bp to nginx/ where nginx.conf is. And you have to do this every time.

├── nginx.conf
├── nginx-bp # <- this repo
│   ├── bootstrap
│   │   └── default.conf
│   ├── enable
│   │   ├── ...

Now I can easily commit my changes pull from you, doing diffs, merging with your modifications and so on.

Boostrap for SSL protocol

Just switched all files with your boilerplate, very well structured!
Can you include boilerplate for SSL?

nowww.conf

It would be great to have a server definition to redirect (301) www-prefixed urls to non-www-prefixed (in contrast with src/nginx-bp/redirects/www.conf).

Confused by default BPCONFPATH

Love the scripts! Thank you :)

When installing I was confused by the fact that the README says to copy the contents of src/ to /etc/nginx but the domman.sh script considers the default location for the sites/ folder to be relative to the bin/ directory which wasn't copied.

The way I imagined it to work was that running domman.sh example.com would create a /etc/nginx/sites/example.conf not /path/to/ngbp-install/src/sites/example.conf.

Are you just expecting that you should always use the optional [-c <confpath>] arg? Or am I missing something?

Не может записать лог

Когда включаю логирование, то возникает ошибка:
[crit] 5045#0: *1 open() "/var/log/nginx/HOST.access.log" failed (13: Permission denied) while logging request

Automagically setting nginx/php domains

• https://github.com/ShepBook/nginx-magic
• https://github.com/fwolf/vpshare
• https://github.com/ammonkc/vhost_script
• https://github.com/caius/nginx-vhost-tools
• https://github.com/hhoover/lazyscripts

Alias doesn't work

I have this config where does not works alias. If I have commented, include default.conf alias works. What is wrong?

server {
        include nginx-bp/ports/http.conf;
        server_name 123;
       access_log 123.log main;
        error_log 1234.log warn;
        root /path/www/;
       include nginx-bp/bootstrap/default.conf;
        index index.html;

       # Static awstats files: HTML files stored in DOCUMENT_ROOT/awstats/
        location /awstatsclasses/ {
                alias /var/www/classes/;
        }

...

Create import script

It would be great to add one more script to bin/ directory, which would import exiting server configs into the nginx boilerplate infrastructure. Regexps should be provided and the scripts should be imported.

As the first approach - copying existing rules (ignoring the basic ones) would be sufficient.

Quite possible that already existing domman.sh could be used with extra parameter.

Could you suggest me about timeouts?

Could you suggest me about timeouts?
What is need to tune?
This page and other, where many pictures, isn't full download. Some pictures isn't show.
Also I see message 504 Gateway Time-out once in a while.

8443 and (no)www redirects

I'm thinking that using 8443 as a port proxied from a load balancer is probably a common enough convention that it deserves attention in the redirects. Currently, it will redirect to to http using the $scheme variable. Perhaps look for x-forwarded-proto at least or does this already happen?

Don't allow POST unless explicitly specified otherwise

It might be a good idea to have an "allow POST" switch. And have POST always switched off unless stated otherwise. It would prevent clients from crafting POST requests to scripts which are not supposed to handle such. It would also protect from cache evading, since POSTs are not cached.

Google, for example, would give you Error 405 (Method Not Allowed)!!1 if you try to post anything to the main page.

backend ошибки

Доброго времени. Установил Nginx-bp + php5-fpm, Yii2. Столкнулся с такой проблемой:
в случае warning, fatal error или еще какие нибудь проблемы случаются, то nginx отдает либо 404 ошибку, либо 500. Логи пишутся, но не всегда. Сейчас в локалке под апачем все работает. Когда переключаю под Nginx то вижу 500 страницу. tail -f /var/log/nginx/default.error.log не реагирует.
Методом дебага, ковыряю код Yii и получается, что код отрабатывает нормально, обратная связь есть, но в каком то месте у меня ошибка (Не удалось отловить), которая на текущий момент выдает 500 ошибку сервера.

можете ли как либо помочь?
php5-fpm display_error = on

В README.md спорные рекомендации

Здравствуйте.

Make sure you have cgi.fix_pathinfo set to "1" or commented out in php.ini

Спорный совет согласно этой статье http://habrahabr.ru/post/100961/ лучше выставить в 0.

Единственный минус, который это даст - $_SERVER['PHP_SELF'] не заполняется, по этому если он используется :( (например в dle насколько я помню видел такое), то стоит добавить в начало стартового скрипта:
$_SERVER['PHP_SELF'] = $_SERVER['SCRIPT_NAME'] . $_SERVER['PATH_INFO'];
Вот это мне кажется и стоит добавить в примечание.

UPD: Кстати в доке по yii2 http://www.yiiframework.com/doc-2.0/guide-installation.html говорят еще и это:

When using this configuration, you should set cgi.fix_pathinfo=0 in the php.ini file in order to avoid many unnecessary system stat() calls.

Помогите перенаправить все запросы на index.php

Прошу прощения, не владею английским.
Я не понимаю, как можно перенаправить все запросы на index.php
500 ошибка каждый раз

Force SSL

I'm having hard time configuring SSL, i'm trying to forse SSL connection with non www, but somehow doesn't get reindirected to SSL, nor hard-coding https:// will make it go in SSL.

I'm editing no-www.conf, where i have removed #, and forced https instead of $scheme:

server
{
include         nginx-bp/ports/ssl.conf;
include         nginx-bp/ssl/keys/default.conf;
include         nginx-bp/ssl/settings.conf;

include         nginx-bp/ports/http.conf;
access_log      off;
server_name     ~^www\.(?<nowww>.*)$;
return          301 https://$nowww$request_uri;
}

Is there a bug, or error in my code?

location php blocked run php in other locations

Hi,
It is not bug, however I will be appreciate for your advice.
If configuration file contain these rules, then next rules will get 404 Erorr

location ~ ^.+\.php(?:/.*)?$
    {
        try_files                       $uri $uri/ /index.php$is_args$args;
        fastcgi_split_path_info         ^(.+.php)(.*)$;
        fastcgi_pass                    unix:/var/run/common-pool-php5-fpm.sock;
        fastcgi_index                   index.php;
        fastcgi_param SCRIPT_FILENAME   $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO         $fastcgi_path_info;
        include                         fastcgi_params;
      skip
        limit_req                       zone=reqPerSec20  burst=150 nodelay;
    }

These rules works fine without above rules.

 location /webmail {
        alias /var/lib/roundcube;
        index index.php;
    }
    location ~ /webmail/.*\.php$ {
        if ($fastcgi_script_name ~ /webmail(/.*\.php)$) {
            set $valid_fastcgi_script_name $1;
        }
        fastcgi_pass                    unix:/var/run/webmail-pool-php5-fpm.sock;
        fastcgi_index                   index.php;
        fastcgi_param SCRIPT_FILENAME   /var/lib/roundcube$valid_fastcgi_script_name;
        include                         fastcgi_params;

      skip

        limit_req                       zone=reqPerSec10  burst=50 nodelay;
    }

    location /roundcube {
        alias /var/lib/roundcube;
    }

    location /roundcube/program/js/tiny_mce/ {
        alias /usr/share/tinymce/www/;
    }

Br,
Rostyslav

Would you mind to add a config for WordPress?

Here is my config made from a different sources :)

# Deliver 404 instead of 403 "Forbidden"
    error_page 403 = 404;

# Do not allow access to files giving away your WordPress version
         location ~ /(\.|wp-config.php|readme.html|licence.txt) {
         return 404;
         }

# Add trailing slash to */wp-admin requests.
    rewrite /wp-admin$ $scheme://$host$uri/ permanent;

# Don't log robots.txt requests
    location = /robots.txt {
        allow all;
        log_not_found off;
        access_log off;
    }

# Rewrite for versioned CSS+JS via filemtime
    location ~* ^.+\.(css|js)$ {
    rewrite ^(.+)\.(\d+)\.(css|js)$ $1.$3 last;
        expires 31536000s;
        access_log off;
        log_not_found off;
        add_header Pragma public;
        add_header Cache-Control "max-age=31536000, public";
    }

# Yoast WordPress SEO
    rewrite ^/sitemap_index\.xml$ /index.php?sitemap=1 last;
    rewrite ^/([^/]+?)-sitemap([0-9]+)?\.xml$ /index.php?sitemap=$1&sitemap_n=$2 last;

#W3 TOTAL CACHE CHECK 
    set $cache_uri $request_uri;

# POST requests and urls with a query string should always go to PHP
    if ($request_method = POST) {
        set $cache_uri 'null cache';
        }   
    if ($query_string != "") {
        set $cache_uri 'null cache';
        }

# Don't cache uris containing the following segments
    if ($request_uri ~* "(/wp-admin/|/xmlrpc.php|/wp-(app|cron|login|register|mail).php|wp-.*.php|/feed/|index.php|wp-comments-popup.php|wp-links-opml.php|wp-locations.php|sitemap(_index)?.xml|[a-z0-9_-]+-sitemap([0-9]+)?.xml)") {
        set $cache_uri 'null cache';
    }

# Don't use the cache for logged in users or recent commenters
    if ($http_cookie ~* "comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_logged_in") {
        set $cache_uri 'null cache';
    }

## Use cached or actual file if they exists, otherwise pass request to WordPress
location / {
        try_files /wp-content/cache/$cache_uri/_index.html $uri $uri/ /index.php?$args ;
        }

# BEGIN W3TC Browser Cache
    location ~ \.(css|htc|js|js2|js3|js4)$ {
    expires 31536000s;
        add_header Pragma "public";
        add_header Cache-Control "max-age=31536000, public, must-revalidate, proxy-revalidate";
        add_header X-Powered-By "W3 Total Cache/0.9.2.11";
        }
    location ~ \.(html|htm|rtf|rtx|svg|svgz|txt|xsd|xsl|xml)$ {
        expires 43200s;
        add_header Pragma "public";
        add_header Cache-Control "max-age=43200, public, must-revalidate, proxy-revalidate";
        add_header X-Powered-By "W3 Total Cache/0.9.2.11";
        }

    location ~ \.(asf|asx|wax|wmv|wmx|avi|bmp|class|divx|doc|docx|eot|exe|gif|gz|gzip|ico|jpg|jpeg|jpe|json|mdb|mid|midi|mov|qt|mp3|m4a|mp4|m4v|mpeg|mpg|mpe|mpp|otf|odb|odc|odf|odg|odp|ods|odt|ogg|pdf|png|pot|pps|ppt|pptx|ra|ram|svg|svgz|swf|tar|tif|tiff|ttf|ttc|wav|wma|wri|xla|xls|xlsx|xlt|xlw|zip)$ {
        expires 31536000s;
        add_header Pragma "public";
        add_header Cache-Control "max-age=31536000, public, must-revalidate, proxy-revalidate";
        add_header X-Powered-By "W3 Total Cache/0.9.2.11";
        }
# END W3TC Browser Cache

# BEGIN W3TC Minify core
    rewrite ^/wp-content/cache/minify.*/w3tc_rewrite_test$ /wp-content/plugins/w3-total-cache/pub/minify.php?w3tc_rewrite_test=1 last;
    rewrite ^/wp-content/cache/minify/(.+/[X]+\.css)$ /wp-content/plugins/w3-total-cache/pub/minify.php?test_file=$1 last;
    rewrite ^/wp-content/cache/minify/(.+\.(css|js))$ /wp-content/plugins/w3-total-cache/pub/minify.php?file=$1 last;
# END W3TC Minify core

Error "405 Not Allowed".

Hello. There was a problem - there is an error 405 Not Allowed. Through trial and error found that error occurs because the lines in the file nginx-bp/enable/php.conf:

fastcgi_param PATH_INFO $ path_info_final;

If you comment out this line, everything works fine.

Best Regards.

access_log not work into if

https://github.com/Umkus/nginx-boilerplate/blob/master/src/nginx-bp/logs/bots.conf

just one question: Does this project support other language besides PHP?

invalid parameter "if=$bot_ua"

nginxnginx: [emerg] invalid parameter "if=$bot_ua" in /etc/nginx/nginx-bp/bootstrap/example.conf:58
nginx: configuration file /etc/nginx/nginx.conf test failed

nginx version: nginx/1.6.0

/var/run/php5-fpm.sock MISS

At first, everything worked, and now the server gives a 500 error in the log is this here record
[17/Jul/2013: 08:32:22 +0400] "GET / HTTP/1.1" 500 5 "-" "Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.36 (KHTML, like Gecko) Ubuntu Chromium/28.0.1500.52 Chrome/28.0.1500.52 Safari/537.36 "0.157 unix :/var/run/php5-fpm.sock MISS

nowhere to be found so that "var/run/php5-fpm.sock MISS" mean

Incorrect caching when session.name is not default

Right now fastcgi_cache_key is using $cookie_PHPSESSID, which only works for apps without user sessions and apps with default value of session.name. In other cases user might see cache from an authorized user.

Boilerplate needs to be able to tell authorized users from anonymous. If this is not easily doable, fastcgi_ignore_headers would have to be commented out by default, to let php handle session caching on its own.

Дополнительные локальные fastcgi_param

Если, вдруг, мне в проекте нужно использовать дополнительные fastcgi_param. Но с ними одна особенность. Описывать их можно на уровнях http, server, location. Так как это, как бы, массив, то при наличии директив fastcgi_param на уровне ниже происходит переопределение всего массива, а не объединение, как хотелось бы. Но не суть.

В данном наборе скриптов fastcgi_param задаются внутри локейшенов для php (по маске или именованного).

Так что, если нужно добавить свои fastcgi_param и при этом не изменять скрипты из набора, просто копируем содержимое файла src/nginx-bp/locations/php.conf себе в блок server и добавляем внутри нужные нам fastcgi_param.

Пример:

#include         nginx-bp/locations/php.conf;
location ~ ^.+\.php(?:/.*)?$
{
    include             local/fastcgi_params;
    include             nginx-bp/enable/php.conf;
}

location @php
{
    include             local/fastcgi_params;
    include             nginx-bp/enable/php.conf;
}

zero size buf in output t:0 r:0 f:1

Hi!
Could you help me? What need to be corrected in the configurations for avoid these errors? zero size buf in output t:0 r:0 f:1

Thanks!

server-configs

Hello, great configs, but take a look at https://github.com/h5bp/server-configs.

"root" directive is duplicate

"root" directive is duplicate in /etc/nginx/nginx-bp/bootstrap/example.conf:1

It is on bootstrap and the site-avaible/example.conf

IMHO it should be in the site configuration only, and the port should be moved to the bootstrap.

Also, renaming example.conf in bootstrap folder to default.config could help to better understanding.

Nginx link signing + video streams

Any thoughts on adding templates for Link signing and mp4 streams?

Lot of redirects if host is not set up

When I edit my local hosts file to send requests to a webserver with latest template files from here, there is a 310 redirect if there is no configuration for the domain. default.error.log contains lines like this:

2013/11/15 18:57:05 [error] 17903#0: 14 testing "/etc/nginx/html" existence failed (2: No such file or directory) while logging request, client: xxx.xxx.xxx.xxx, server: ~^www.(?.)$, request: "GET / HTTP/1.1", host: "www.test.com"

What about to add cache control?

What about to add cache control lice this config?

location ~ /purge(/.*) {
allow 127.0.0.1;
deny all;
fastcgi_cache_purge cacheGlobal "$scheme://$host$1";
}

403 on php in subfolders

• nginx version: nginx/1.4.2
• PHP 5.4.17-1~dotdeb.0, Zend Engine v2.4.0, Xdebug v2.2.3 - php_fpm
• Debian GNU/Linux 7.0 (wheezy)

All standard.
Site conf

server {
    listen 80;
    server_name test.local;
    root /var/www/web/;

    include         nginx-bp/cache.conf;
    include         nginx-bp/limits/methods.conf;

    include         nginx-bp/locations/php.conf;
    include         nginx-bp/locations/favicon.conf;
    include         nginx-bp/locations/favicon_apple.conf;
    include         nginx-bp/locations/static.conf;
    include         nginx-bp/locations/system.conf;

    location /
    {
        include     nginx-bp/logs/bots.conf;
        try_files   $uri $uri/ /index.php;
        auth_basic "Admin Zone";
        auth_basic_user_file /var/passwd/passwords;
    }
}

In "/var/www/web/" I have "index.php" and subfolder "test" also with "index.php". In "index.php" I have only "phpinfo".

http://test.local/ or http://test.local/index.php - I see phpinfo
http://test.local/test/ or http://test.local/test/index.php - I see 403

What should I do?

Failed create /var/cache/nginx/global on start

I'm trying the nginx-bp. Have done on pretty clean Ubuntu Desktop 13.04:

sudo apt-get install nginx
git clone https://github.com/Umkus/nginx-boilerplate
edited nginx-boilerplate/src/nginx-bp/system.conf to use my user account (zk7ss4x)
cd to nginx-boilerplate/src/build
sudo sh ./run.sh

Here's output:
zk7ss4x@HP-Compaq:~/Projects/own/nginx-boilerplate/build$ sudo sh ./run.sh
nginx: [emerg] mkdir() "/var/cache/nginx/global" failed (2: No such file or directory)

Is something missing from "Try it" instructions?

Странные правила лишенные смысла: src/nginx-bp/enable/php.conf

Здравствуйте.

Куча условий которые дублируют функционал стандартных способов заполнения переменных nginx.

fastcgi_split_path_info ^(.+?\.php)(/.*)$;
if ($uri ~ ^(?<script_name>.+\.php)?(?<path_info>/.*)?$) {}

fastcgi_split_path_info - и так заполняет $fastcgi_path_info и $fastcgi_script_name тем же самым содержимым. Исходя из этого, смысла в дальнейших if нет.

Свой вариант предлагаю в pull request

Forbidden when '.' in dirname

bitrix/components/bitrix/pull.request/ajax.php - forbidden nginx
bitrix/components/bitrix/pull_request/ajax.php - all ok

with origin config all ok

301 редирект nowww -> www

Если просто включить www.conf в nginx.conf, то 301 редиркта не происходит. Надо куда-то в другое место?

PHP caching

What's the reasoning behind the following line that can be found in so many nginx tutorials?

fastcgi_ignore_headers          "Cache-Control" "Expires";

Can't PHP apps decide what's cached and what's not?