gaja-group
/
server-configs-nginx
mirror of https://github.com/h5bp/server-configs-nginx
2
0
Fork 0
Code Issues Releases Wiki Activity

Remove outdated docs and fix repo structure 

Trying to make maintenance as easier as we can
This commit is contained in:
Léo Colombaro 2019-02-04 14:09:06 +01:00
parent 76be9604e3
commit 8919496406
No known key found for this signature in database
GPG Key ID: 687B480A6D4F735F
10 changed files with 129 additions and 292 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.gitignore vendored
View File

@ -1,3 +1,4 @@
/logs/ /logs/
/sites-enabled/* /conf.d/*.conf
!/sites-enabled/.gitkeep !/conf.d/.default.conf
!/conf.d/no-ssl.default.conf

123
README.md
View File

@ -6,11 +6,126 @@ ensuring that resources are served with the correct content-type and are
accessible, if needed, even cross-domain. accessible, if needed, even cross-domain.
## Documentation ## Getting Started
The [documentation](doc/TOC.md) is bundled with * [Nginx Beginners Guide](https://nginx.org/en/docs/beginners_guide.html)
the project, which makes it readily available for offline reading and provides a * [Nginx Request Processing](https://nginx.org/en/docs/http/request_processing.html)
useful starting point for any documentation you want to write about your project. * [How Nginx works](docs/getting-started.md) — Understanding nginx, and how it differs from other webservers.
### Basic structure
This repository has the following structure:
```
./
├── conf.d/
│ ├── default.conf
│ └── templates/
├── h5bp/
│ ├── basic.conf
│ ├── location/
│ └── .../
├── mime.types
└── nginx.conf
```
* **`conf.d/`**
This directory should contain all of the server definitions.
Except if they are dot prefixed or non .conf extension, all files in this
folder **are** loaded automatically.
* **`templates` folder**
Files in this folder contain a `server{}` template for secure and non-secure hosts.
They are intended to be copied in the `conf.d` folder with all `example.com`
occurrences changed to the target host.
* **`h5bp/`**
This directory contains config snippets (mixins) to be included as desired.
There are two types of config files provided, individual config snippets and
combined config files which provide convenient defaults.
* **`basic.conf`**
This file loads a small subset of the rules provided by this repository to add
expires headers, allow cross domain fonts and protect system files from web
access.
* **`location/`**
Files in this folder contain one or more location directives. They are intended
to be loaded in the server context (or, in a nested location block).
* **`mime.types`**
The mime.types file is responsible for mapping file extensions to mime types.
* **`nginx.conf`**
The main nginx config file.
### Other resources
* [Troubleshooting](docs/troubleshooting.md) — Dealing with commonly-encountered errors.
* [Hotlink protection](docs/hotlink-protection.md)
## Usage
### As a reference
To use as reference requires no special installation steps, download/checkout the
repository to a convenient location and adapt your existing nginx configuration
incorporating the desired functionality from this repository.
### Directly
To use directly, replace the nginx config directory with this repository. for example:
```shell
nginx stop
cd /etc
mv nginx nginx-previous
git clone https://github.com/h5bp/server-configs-nginx.git nginx
# install-specific edits
nginx start
```
### Manage sites
```bash
$ cd /etc/nginx/conf.d
```
* Creating a new site
```bash
$ cp templates/example.com.conf .actual-hostname.conf
$ sed -i 's/example.com/actual-hostname/g' .actual-hostname.conf
```
* Enabling a site
```bash
$ mv .actual-hostname.conf actual-hostname.conf
```
* Disabling a site
```bash
$ mv actual-hostname.conf .actual-hostname.conf
```
```bash
$ nginx reload
```
## Support
* Nginx v**1.6.0**+
## Contributing ## Contributing

22
doc/TOC.md
View File

@ -1,22 +0,0 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
# Nginx Server Configs documentation:
## Getting started
* [Usage](usage.md) — Overview of the project contents.
* [Nginx.conf](nginx-conf.md) — General introduction to the main config file.
* [How Nginx works](how-nginx-works.md) — Understanding nginx, and how it differs from other webservers.
* [Common problems](common-problems.md) — Dealing with commonly-encountered errors.
## Example tasks
* [Hotlink protection](examples/hotlink-protection.md)
## Related projects
* [HTML5 Boilerplate](https://html5boilerplate.com) — professional front-end
template.
* [Server configs](https://github.com/h5bp/server-configs) — Configs for
other web servers.
* [Mozilla SSL Configuration Generator](https://mozilla.github.io/server-side-tls/ssl-config-generator/) — generate Mozilla Security recommended web server configs.

66
doc/how-nginx-works.md
View File

@ -1,66 +0,0 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
| [Documentation table of contents](TOC.md)
# How Nginx works
If you're familiar with any other webserver, some aspects of
[the way Nginx works](https://nginx.org/en/docs/http/request_processing.html)
can cause confusion. This document aims to highlight differences or features
which may trip up new users.
## Nginx will only use one location block
A [location block (directive)](https://nginx.org/en/docs/http/ngx_http_core_module.html#location)
defines the behavior for a given request which matches the location url pattern. The block used
is whichever is the most specific for the given request, the rules for
precedence can be found in [Nginx's documentation](https://nginx.org/en/docs/http/ngx_http_core_module.html#location).
It is very important when writing nginx configuration files to understand that
only one location block will be used by Nginx. When in doubt a useful technique
to identify which location block is to add a header:
# Make sure js files are served with a long expire
location ~ /something {
add_header "section" "something location";
...
}
location /something-else {
add_header "section" "something else location";
...
}
In the headers for a response, the header added from the block which matched
will be included:
$ curl -I "http://nginx.h5bp.dev/something"
...
section: something location
There are some significant consequences to this behavior such as it _not_ being
possible to build configuration files from small, overlapping, location blocks.
## try_files in the server context does not always apply
Consider the following server block:
server {
listen 80;
server_name example.com;
root /var/www/example.com;
try_files $uri $uri/ /fallback.html;
location ~ ^/somefolder {
...
}
}
It might be expected that a request for `http://example.com/somefolder/doesnt-exist`
would result in the contents of `/fallback.html` - but this is not the case. the
`try_files` directive in the server context _only applies if no location block
matches_, it is not a default which location blocks inherit.

55
doc/nginx-conf.md
View File

@ -1,55 +0,0 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
| [Documentation table of contents](TOC.md)
# Nginx.conf
The `nginx.conf` file is the main config file for nginx, which either defines
or includes the whole configuration for the server.
When editing or defining an nginx configuration file - take care to note in
which [context](https://nginx.org/en/docs/beginners_guide.html#conf_structure)
a directive applies.
Below are some notes on a few of the more important/commonly-edited directives.
For detailed information on any particular directive, please see
[the official documentation](https://nginx.org/en/docs/).
## user
The [user directive](https://nginx.org/en/docs/ngx_core_module.html#user)
indicates which user the server will run as. This is typically a user
specifically for web usage such as "www" "www-data".
The webserver user, and file permissions for any application, should be defined/chosen
following [the principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)
i.e., sufficient privileges to function correctly but no more than that.
## worker_processes
The [worker_processes directive](https://nginx.org/en/docs/ngx_core_module.html#worker_processes)
broadly defines the number of connections nginx can process.
As of version 1.2.5+ and 1.3.8+, nginx supports the value "auto" which will
automatically detect an appropriate value. In earlier versions setting to
the number of CPUs is a good default/starting point.
## error_log
The [error_log directive](https://nginx.org/en/docs/ngx_core_module.html#error_log)
can be defined/overriden in any context. The directive in the main context
defines the log file to use unless otherwise overriden (at http, server or location
level). This must point to a location writable to the webserver user.
The location for log files varies depending on the operating system; one technique
to allow the config files to be ignorant of this is to symlink `/etc/nginx/logs`
to where you would like log files to be located. e.g.:
mkdir /var/log/nginx
cd /etc/nginx
ln -s /var/log/nginx logs
## pid
The [pid directive](https://nginx.org/en/docs/ngx_core_module.html#pid) is used
by nginx to store the process id of the main process. This must point to a writable
location.

120
doc/usage.md
View File

@ -1,120 +0,0 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
| [Documentation table of contents](TOC.md)
# Usage
## Requirements
* nginx version 1.6.0+
There are two ways to make use of the contents of this repository, as a reference
or directly as the source for nginx to run from. A number of config snippets are
provided allowing you to pick and choose which features to allow/expose - some
snippets are dependent on other features in this repository. For example rules that
rely on a specific mime type for a given file extension, expect/rely the use of the
bundled `mime.types` file.
## Using as a reference
To use as reference requires no special installation steps, download/checkout the
repository to a convenient location and adapt your existing nginx configuration
incorporating the desired functionality from this repository.
## Using directly
To use directly, replace the nginx config directory with this repository. for example:
/etc/init.d/nginx stop
cd /etc
mv nginx nginx-previous
git clone https://github.com/h5bp/server-configs-nginx.git nginx
# install-specific edits
/etc/init.d/nginx start
Install specific edits will vary from server to user, see [Getting started](getting-started.md)
for a description of the required steps.
## Basic structure
This repository has the following structure:
```
./
├── doc/
├── conf.d/
│ ├── default.conf
│ └── templates/
├── h5bp/
│ ├── basic.conf
│ ├── location/
│ └── ...
├── mime.types
└── nginx.conf
```
Below is a general description of each section
### h5bp
This directory contains config snippets (mixins) to be included as desired.
There are two types of config files provided, individual config snippets and
combined config files which provide convenient defaults.
* `basic.conf`
This file loads a small subset of the rules provided by this repository to add
expires headers, allow cross domain fonts and protect system files from web
access.
* `location` folder
Files in this folder contain one or more location directives. They are intended
to be loaded in the server context (or, in a nested location block).
### conf.d
This directory should contain all of the server definitions.
Except if they are dot prefixed or non .conf extension, all files in this
folder **are** loaded automatically.
* `templates` folder
Files in this folder contain a server{} template for secure and non-secure hosts.
They are intended to be copied in the `conf.d` folder with all `example.com`
occurrences changed to the target host.
#### Usage
```bash
$ cd /etc/nginx/conf.d
```
* Creating a new site
```bash
$ cp templates/example.com.conf actual-hostname.conf
$ sed -i 's/example.com/actual-hostname/g' actual-hostname.conf
```
* Enabling a site
```bash
$ mv .actual-hostname.conf actual-hostname.conf
```
* Disabling a site
```bash
$ mv actual-hostname.conf .actual-hostname.conf
```
```bash
$ /etc/init.d/nginx reload
```
### mime.types
The mime.types file is responsible for mapping file extensions to mime types.
### nginx.conf
The main nginx config file. [About nginx.conf](nginx-conf.md).

19
doc/getting-started.md → docs/getting-started.md
View File

@ -1,5 +1,4 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx) [Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
| [Documentation table of contents](TOC.md)
# Getting started # Getting started
@ -56,22 +55,8 @@ If you see:
Or similar, there is still a problem to resolve before continuing. Or similar, there is still a problem to resolve before continuing.
## Creating a site definition
An example server definition is provided in `sites-available/example.com`. Copy the file to
`sites-available/yourdomainname.com` and edit appropriately. Verify specifically that
the hostname (`example.com`) and the root are specified correctly.
## Enabling a site
Activate the new site by linking `yourdomainname.com` into the `sites-enabled` directory:
cd /etc/nginx/sites-enabled
ln -s ../sites-available/yourdomainname.com .
This will make the server active the next time nginx (re)starts.
## Verify config and restart nginx ## Verify config and restart nginx
Verify the config and restart nginx to apply the changes. Verify the config and restart nginx to apply the changes.
To verify nginx config (Tests default nginx config file) To verify nginx config (Tests default nginx config file)
@ -88,4 +73,4 @@ This will test the nginx config file and throws error if any. Otherwise test is
Finally reload nginx to apply the changes. Finally reload nginx to apply the changes.
/etc/init.d/nginx reload nginx reload

1
doc/examples/hotlink-protection.md → docs/hotlink-protection.md
View File

@ -1,5 +1,4 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx) [Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
| [Documentation table of contents](../TOC.md)
# Hotlink Protection # Hotlink Protection

3
doc/common-problems.md → docs/troubleshooting.md
View File

@ -1,7 +1,6 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx) [Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
| [Documentation table of contents](TOC.md)
# Common Problems # Troubleshooting
## types_hash errors ## types_hash errors

7
nginx.conf
View File

@ -4,7 +4,8 @@
# Run as a unique, less privileged user for security reasons. # Run as a unique, less privileged user for security reasons.
# Default: nobody nobody # Default: nobody nobody
# https://nginx.org/en/docs/ngx_core_module.html#user # https://nginx.org/en/docs/ngx_core_module.html#user
user www www; # https://en.wikipedia.org/wiki/Principle_of_least_privilege
user www-data;
# Sets the worker threads to the number of CPU cores available in the system for best performance. # Sets the worker threads to the number of CPU cores available in the system for best performance.
# Should be > the number of CPU cores. # Should be > the number of CPU cores.
@ -37,7 +38,7 @@ events {
# This is only used when you don't override it on a server{} level # This is only used when you don't override it on a server{} level
# Default: logs/error.log error # Default: logs/error.log error
# https://nginx.org/en/docs/ngx_core_module.html#error_log # https://nginx.org/en/docs/ngx_core_module.html#error_log
error_log logs/error.log warn; error_log /var/log/nginx/error.log warn;
# The file storing the process ID of the main process # The file storing the process ID of the main process
# Default: logs/nginx.pid # Default: logs/nginx.pid
@ -84,7 +85,7 @@ http {
# This is only used when you don't override it on a server{} level # This is only used when you don't override it on a server{} level
# Default: logs/access.log combined # Default: logs/access.log combined
# https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log # https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log
access_log logs/access.log main; access_log /var/log/nginx/access.log main;
# How long to allow each connection to stay idle. # How long to allow each connection to stay idle.
# Longer values are better for each individual client, particularly for SSL, # Longer values are better for each individual client, particularly for SSL,