Skip to content

Commit

Permalink
Restructure README and improve guides
Browse files Browse the repository at this point in the history 
Closes #218
  • Loading branch information
@LeoColomb
LeoColomb committed Apr 13, 2020
1 parent 644805e commit 6862ac1
Showing 1 changed file with 133 additions and 123 deletions.
256 changes: 133 additions & 123 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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)

Expand All @@ -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 `<VirtualHost/>` 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

Expand Down Expand Up @@ -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`
Expand All @@ -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 `<VirtualHost/>` 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
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 6862ac1

Please sign in to comment.