From 8919496406ccb0fabbd6df55fbe14a20a9926d5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A9o=20Colombaro?= Date: Mon, 4 Feb 2019 14:09:06 +0100 Subject: [PATCH] Remove outdated docs and fix repo structure Trying to make maintenance as easier as we can --- .gitignore | 5 +- README.md | 123 +++++++++++++++++- doc/TOC.md | 22 ---- doc/how-nginx-works.md | 66 ---------- doc/nginx-conf.md | 55 -------- doc/usage.md | 120 ----------------- {doc => docs}/getting-started.md | 19 +-- {doc/examples => docs}/hotlink-protection.md | 1 - .../troubleshooting.md | 3 +- nginx.conf | 7 +- 10 files changed, 129 insertions(+), 292 deletions(-) delete mode 100644 doc/TOC.md delete mode 100644 doc/how-nginx-works.md delete mode 100644 doc/nginx-conf.md delete mode 100644 doc/usage.md rename {doc => docs}/getting-started.md (78%) rename {doc/examples => docs}/hotlink-protection.md (97%) rename doc/common-problems.md => docs/troubleshooting.md (98%) diff --git a/.gitignore b/.gitignore index 4fcba20..29b0d3b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ /logs/ -/sites-enabled/* -!/sites-enabled/.gitkeep +/conf.d/*.conf +!/conf.d/.default.conf +!/conf.d/no-ssl.default.conf diff --git a/README.md b/README.md index 1507607..05d9b4b 100644 --- a/README.md +++ b/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 diff --git a/doc/TOC.md b/doc/TOC.md deleted file mode 100644 index c9a46d8..0000000 --- a/doc/TOC.md +++ /dev/null @@ -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. diff --git a/doc/how-nginx-works.md b/doc/how-nginx-works.md deleted file mode 100644 index 183bb79..0000000 --- a/doc/how-nginx-works.md +++ /dev/null @@ -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. - diff --git a/doc/nginx-conf.md b/doc/nginx-conf.md deleted file mode 100644 index 78d7f5c..0000000 --- a/doc/nginx-conf.md +++ /dev/null @@ -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. diff --git a/doc/usage.md b/doc/usage.md deleted file mode 100644 index 405e12e..0000000 --- a/doc/usage.md +++ /dev/null @@ -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). diff --git a/doc/getting-started.md b/docs/getting-started.md similarity index 78% rename from doc/getting-started.md rename to docs/getting-started.md index bc0d654..c568a73 100644 --- a/doc/getting-started.md +++ b/docs/getting-started.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 diff --git a/doc/examples/hotlink-protection.md b/docs/hotlink-protection.md similarity index 97% rename from doc/examples/hotlink-protection.md rename to docs/hotlink-protection.md index 1710245..915a276 100644 --- a/doc/examples/hotlink-protection.md +++ b/docs/hotlink-protection.md @@ -1,5 +1,4 @@ [Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx) - | [Documentation table of contents](../TOC.md) # Hotlink Protection diff --git a/doc/common-problems.md b/docs/troubleshooting.md similarity index 98% rename from doc/common-problems.md rename to docs/troubleshooting.md index d44a7b2..d4b182e 100644 --- a/doc/common-problems.md +++ b/docs/troubleshooting.md @@ -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 diff --git a/nginx.conf b/nginx.conf index 70f1083..3d83de1 100644 --- a/nginx.conf +++ b/nginx.conf @@ -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,