From 6862ac17ed60042c4eb47b56c8da055e99ad4dac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A9o=20Colombaro?= Date: Mon, 13 Apr 2020 21:43:46 +0200 Subject: [PATCH] Restructure README and improve guides Closes #218 --- README.md | 256 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 133 insertions(+), 123 deletions(-) diff --git a/README.md b/README.md index 5071f233..e78913a4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# [Apache Server Configs](https://github.com/h5bp/server-configs-apache/) +# [Apache Server Configs](https://github.com/h5bp/server-configs-apache) [![Test](https://github.com/h5bp/server-configs-apache/workflows/server/badge.svg)](https://github.com/h5bp/server-configs-apache/actions?query=workflow%3Aserver) @@ -10,93 +10,49 @@ accessible, if needed, even cross-domain. ## Getting Started -There are a few options for getting the Apache server configs. +There are a two options for getting the Apache server configs: +* If you have access to the [main server configuration + file](https://httpd.apache.org/docs/current/configuring.html#main) + (usually called `httpd.conf`), you should configure Apache by this way. + This is usually the recommended way, as using `.htaccess` files [slows + down](https://httpd.apache.org/docs/current/howto/htaccess.html#when) + Apache! +* If you don't have access to it, which is quite common with hosting services, + checkout the [`.htaccess` guide](#htaccess-file). -See also the [Apache Getting Started](https://httpd.apache.org/docs/current/getting-started.html). - -### Using the httpd configuration - -If you have access to the [main server configuration -file](https://httpd.apache.org/docs/current/configuring.html#main) -(usually called `httpd.conf`), you should configure Apache by this way. -This is usually the recommended way, as using `.htaccess` files [slows -down](https://httpd.apache.org/docs/current/howto/htaccess.html#when) -Apache! - -Getting options: -* Download the [zip archive](https://github.com/h5bp/server-configs-apache/archive/3.2.1.zip) -* Checkout directly: - ```shell - apache2ctl stop - cd /usr/local - mv apache2 apache2-previous - git clone https://github.com/h5bp/server-configs-apache.git apache2 - # install-specific edits - apache2ctl start - ``` - -See [Apache httpd configuration usage guide](#Apache-httpd-configuration). - -### Using the `.htaccess` file - -If you don't have access, which is quite common with hosting services, -just copy the `.htaccess` file in the root of the website. - -Getting options: -* Download the `h5bp.htaccess` on the [latest release](https://github.com/h5bp/server-configs-apache/releases/latest) -* Install them via [npm](https://www.npmjs.com/): `npm install --save-dev apache-server-configs` - Inside the `dist/` folder, you'll find a ready-to-use `.htaccess` file. - - -## Usage - -### Basic structure - -This repository has the following structure: - -``` -./ -├── vhosts/ -│ ├── 000-default.conf -│ └── templates/ -├── h5bp/ -│ ├── basic.conf -│ └── .../ -└── httpd.conf -``` - -* **`vhosts/`** - - This directory should contain all the server definitions. - - Except if they are dot prefixed or non .conf extension, all files in this - folder **are** loaded automatically. +Using the Apache server configs repo directly has a few required steps to be able to work. - * **`templates` folder** - - Files in this folder contain a `` template for secure and non-secure hosts. - They are intended to be copied in the `vhosts` folder with all `example.com` - occurrences changed to the target host. +See also the [Apache Getting Started](https://httpd.apache.org/docs/current/getting-started.html). -* **`h5bp/`** +### Check `httpd.conf` settings - 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. +The first thing to check is that the `httpd.conf` file contains appropriate values for +your specific install. - * **`basic.conf`** +Most specific variables are: +* `ServerRoot` +* `User` +* `Group` +* `ErrorLog` +* `CustomLog` +* `TypesConfig` (ensure that the path for the `mime.types` file is valid) - 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. - The `basic.conf` file includes the rules which are recommended to always be - defined. +### Apache test and restart -* **`httpd.conf`** +* To verify Apache config + ```shell + $ apache2 -t + ``` - The main Apache config file. +* To verify Apache config with a custom file + ```shell + $ apache2 -t -f httpd.conf + ``` +* To reload Apache and apply new config + ```shell + $ apache2ctl reload + ``` ### Enable Apache httpd modules @@ -131,7 +87,7 @@ used to install Apache. `sudo a2enmod setenvif headers deflate filter expires rewrite include` -2. Restart apache by using the following command, so the new configuration takes +2. Restart apache by using the following command so the new configuration takes effect. `sudo /etc/init.d/apache2 restart` @@ -152,41 +108,83 @@ used to install Apache. * **XAMPP**: `/Applications/XAMPP/etc/httpd.conf` * **WAMP**: `C:\apache\conf\httpd.conf` - Open the file in a text editor and uncomment all the required modules. + Open the file in a text editor and uncomment all of the required modules. Once you have done so, reset MAMP/WAMP/XAMPP. -### Apache httpd configuration +### Basic structure -#### Check `httpd.conf` settings +This repository has the following structure: -The first thing to check is that the `httpd.conf` file contains appropriate values for -your specific install. +``` +./ +├── vhosts/ +│ ├── 000-default.conf +│ └── templates/ +├── h5bp/ +│ ├── basic.conf +│ └── .../ +└── httpd.conf +``` -Most specific variables are: -* `ServerRoot` -* `User` -* `Group` -* `ErrorLog` -* `CustomLog` +* **`vhosts/`** -#### Apache test and restart + This directory should contain all the server definitions. -* To verify Apache config - ```shell - $ apache2 -t - ``` + Except if they are dot prefixed or non `.conf` extension, all files in this + folder **are** loaded automatically. -* To verify Apache config with a custom file - ```shell - $ apache2 -t -f httpd.conf - ``` + * **`templates` folder** -* To reload Apache and apply new config - ```shell - $ apache2ctl reload - ``` + Files in this folder contain a `` template for secure and non-secure hosts. + They are intended to be copied in the `vhosts` 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. + The `basic.conf` file includes the rules which are recommended to always be + defined. + +* **`httpd.conf`** + + The main Apache config file. + + +## Usage + +### As a reference -#### Manage sites +To use as reference requires no special installation steps, download/checkout the +repository to a convenient location and adapt your existing httpd configuration +incorporating the desired functionality from this repository. + +Download the [latest release archive](https://github.com/h5bp/server-configs-apache/releases/latest). + +### Directly + +To use directly, add httpd config files from this repository. +For example: + +```shell +apache2ctl stop +git clone https://github.com/h5bp/server-configs-apache.git /tmp/h5bp-apache +cd /usr/local +cp -r apache2 apache2-previous +cp -r /tmp/h5bp-apache/* apache2 +# install-specific edits +apache2ctl start +``` + +### Manage sites ```bash $ cd /usr/local/apache2/vhosts @@ -213,7 +211,19 @@ $ apache2ctl reload ``` -## Custom `.htaccess` builds +## `.htaccess` file + +### Usage + +Just copy the `.htaccess` file in the root of the website. + +Getting options: +* Download the `h5bp.htaccess` on the [latest release](https://github.com/h5bp/server-configs-apache/releases/latest) + and rename the file to `.htaccess` +* Install them via [npm](https://www.npmjs.com/): `npm install --save-dev apache-server-configs` + Inside the `dist/` folder, you'll find a ready-to-use `.htaccess` file. + +### Custom `.htaccess` builds Security, mime-type, and caching best practices evolve, and so should do your `.htaccess` file. In the past, with each new *Apache Server Configs* release @@ -224,13 +234,13 @@ The [**build script**](#build-script-buildsh) with its re-usable and customizabl [**build configuration**](#configuration-file-htaccessconf) lets you easily update your `.htaccess` file. Each new `.htaccess` build will contain the updated *Apache Server Configs* source files, enabled or commented-out according -to your settings in the *htaccess.conf* of your project root. +to your settings in the `htaccess.conf` of your project root. -### Configuration file: *htaccess.conf* +#### Configuration file: `htaccess.conf` Allows you to define which module to [enable](#enabling-modules) or [disable](#disabling-modules) for your project. Just copy the default -[**htaccess.conf**](https://github.com/h5bp/server-configs-apache/blob/master/bin/htaccess.conf) +[`htaccess.conf`](https://github.com/h5bp/server-configs-apache/blob/master/bin/htaccess.conf) from this repo into your project directory. Adjust to your needs, and/or [add custom code](#adding-custom-modules) snippets you need for your project. Its syntax is straight and pretty much self-explanatory: @@ -247,11 +257,11 @@ omit "src/example-module/not-needed-at-all.conf" ... more modules ... ``` -#### Disabling modules +##### Disabling modules For example, the *“Cross-origin web fonts”* snippet is always included in our pre-built `.htaccess` file and enabled. If your project does not deal -with web fonts, you can **disable** or **omit** this section: +with web fonts, you can `disable` or `omit` this section: This will comment out the section: @@ -265,17 +275,17 @@ disable "h5bp/cross-origin/web_fonts.conf" omit "h5bp/cross-origin/web_fonts.conf" ``` -#### Enabling modules +##### Enabling modules For example, the *“Forcing https://”* snippet is disabled by default, although being included in our pre-built `.htaccess`. To enable this -snippet, change the **disable** keyword to **enable:** +snippet, change the `disable` keyword to `enable`: ``` enable "h5bp/rewrites/rewrite_http_to_https.conf" ``` -#### Adding custom modules +##### Adding custom modules Imagine you're passing all requests to non-existing files to your favourite web framework. The according @@ -286,21 +296,21 @@ snippet would go like this: FallbackResource index.php ``` -Store this snippet in a file, e.g. **config/framework_rewrites.conf,** and add -a reference in your **htaccess.conf:** +Store this snippet in a file, e.g. `config/framework_rewrites.conf`, and add +a reference in your `htaccess.conf`: ``` # PROJECT MODULES enable "config/framework_rewrites.conf" ``` -### Build script: *build.sh* +#### Build script: `build.sh` Dive into your project root and call the build script from wherever you cloned the repo. Here are three examples: -**1. Create a default .htaccess** -in current work directory. An existing **htaccess.conf** in this directory will +**1. Create a default `.htaccess`** +in current work directory. An existing `htaccess.conf` in this directory will be used; if none is present, the [**default configuration**](https://github.com/h5bp/server-configs-apache/blob/master/bin/htaccess.conf) will apply. @@ -316,7 +326,7 @@ $ path/to/server-configs-apache/bin/build.sh **2. Custom output location** Just add output path and filename as parameter. By the way, if there's an -existing *.htaccess* file, the build script will create a backup. +existing `.htaccess` file, the build script will create a backup. ```bash $ path/to/server-configs-apache/bin/build.sh htdocs/.htaccess @@ -325,9 +335,9 @@ $ path/to/server-configs-apache/bin/build.sh htdocs/.htaccess [✔] Moved in place: 'htdocs/.htaccess' ``` -**3. Custom .htaccess configuration** -Why not maintain your personal **~/htaccess.conf?** This example creates a -*.htaccess* in current work directory, according to your favourite settings +**3. Custom `.htaccess` configuration** +Why not maintain your personal `~/htaccess.conf`? This example creates a +`.htaccess` in current work directory, according to your favourite settings you may have stored in your `$HOME` directory: ```bash