Remove outdated docs and fix repo structure
Trying to make maintenance as easier as we can
This commit is contained in:
Léo Colombaro
parent
76be9604e3
commit
8919496406
|
|
@ -1,3 +1,4 @@
|
|||
/logs/
|
||||
/sites-enabled/*
|
||||
!/sites-enabled/.gitkeep
|
||||
/conf.d/*.conf
|
||||
!/conf.d/.default.conf
|
||||
!/conf.d/no-ssl.default.conf
|
||||
|
|
|
|||
123
README.md
123
README.md
|
|
@ -6,11 +6,126 @@ ensuring that resources are served with the correct content-type and are
|
|||
accessible, if needed, even cross-domain.
|
||||
|
||||
|
||||
## Documentation
|
||||
## Getting Started
|
||||
|
||||
The [documentation](doc/TOC.md) is bundled with
|
||||
the project, which makes it readily available for offline reading and provides a
|
||||
useful starting point for any documentation you want to write about your project.
|
||||
* [Nginx Beginners Guide](https://nginx.org/en/docs/beginners_guide.html)
|
||||
* [Nginx Request Processing](https://nginx.org/en/docs/http/request_processing.html)
|
||||
* [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
|
||||
|
|
|
|||
22
doc/TOC.md
22
doc/TOC.md
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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
120
doc/usage.md
|
|
@ -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).
|
||||
|
|
@ -1,5 +1,4 @@
|
|||
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
|
||||
| [Documentation table of contents](TOC.md)
|
||||
|
||||
# Getting started
|
||||
|
||||
|
|
@ -56,22 +55,8 @@ If you see:
|
|||
|
||||
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 the config and restart nginx to apply the changes.
|
||||
|
||||
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.
|
||||
|
||||
/etc/init.d/nginx reload
|
||||
nginx reload
|
||||
|
|
@ -1,5 +1,4 @@
|
|||
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
|
||||
| [Documentation table of contents](../TOC.md)
|
||||
|
||||
# Hotlink Protection
|
||||
|
||||
|
|
@ -1,7 +1,6 @@
|
|||
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
|
||||
| [Documentation table of contents](TOC.md)
|
||||
|
||||
# Common Problems
|
||||
# Troubleshooting
|
||||
|
||||
## types_hash errors
|
||||
|
||||
|
|
@ -4,7 +4,8 @@
|
|||
# Run as a unique, less privileged user for security reasons.
|
||||
# Default: nobody nobody
|
||||
# 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.
|
||||
# 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
|
||||
# Default: logs/error.log error
|
||||
# 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
|
||||
# Default: logs/nginx.pid
|
||||
|
|
@ -84,7 +85,7 @@ http {
|
|||
# This is only used when you don't override it on a server{} level
|
||||
# Default: logs/access.log combined
|
||||
# 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.
|
||||
# Longer values are better for each individual client, particularly for SSL,
|
||||
|
|
|
|||
Loading…
Reference in New Issue