Update README and documentation to close refactoring.

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/authelia-title.png" width="350" title="Authelia">
+  <img src="./docs/images/authelia-title.png" width="350" title="Authelia">
 </p>
 
   [![license](https://img.shields.io/badge/license-Apache%202.0-green.svg)][Apache 2.0]
@@ -16,25 +16,25 @@ It acts as a companion of reverse proxies like [nginx] or [Traefik] by handling
 
 
 <p align="center">
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/authelia.logo.png" height="100"/>
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/plus.png" height="100"/>
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/nginx.logo.png" height="100"/>
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/traefik.logo.png" height="100"/>  
+  <img src="./docs/images/logos/authelia.logo.png" height="100"/>
+  <img src="./docs/images/plus.png" height="100"/>
+  <img src="./docs/images/logos/nginx.logo.png" height="100"/>
+  <img src="./docs/images/logos/traefik.logo.png" height="100"/>  
 </p>
 
 **Authelia** can be installed as a standalone service using Docker or NPM
 but can also be deployed easily on [Kubernetes] leveraging ingress controllers and ingress configuration.
 
 <p align="center">
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/kubernetes.logo.png" height="100"/>
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/docker.logo.png" width="100">
+  <img src="./docs/images/logos/kubernetes.logo.png" height="100"/>
+  <img src="./docs/images/logos/docker.logo.png" width="100">
 </p>
 
 Here is what Authelia's portal looks like
 
 <p align="center">
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/first_factor.png" width="400" />
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/use-another-method.png" width="400" />
+  <img src="./docs/images/1FA.png" width="400" />
+  <img src="./docs/images/2FA-METHODS.png" width="400" />
 </p>
 
 ## Features summary
@@ -42,9 +42,9 @@ Here is what Authelia's portal looks like
 Here is the list of the main available features:
 
 * Several kind of second factor:
-  * **[Security Key (U2F)](https://github.com/clems4ever/authelia/blob/master/docs/2factor/security-key.md)** with [Yubikey].
-  * **[Time-based One-Time password](https://github.com/clems4ever/authelia/blob/master/docs/2factor/time-based-one-time-password.md)** with [Google Authenticator].
-  * **[Mobile Push Notifications](https://github.com/clems4ever/authelia/blob/master/docs/2factor/duo-push-notifications.md)** with [Duo](https://duo.com/).
+  * **[Security Key (U2F)](./docs/2factor/security-key.md)** with [Yubikey].
+  * **[Time-based One-Time password](./docs/2factor/time-based-one-time-password.md)** with [Google Authenticator].
+  * **[Mobile Push Notifications](./docs/2factor/duo-push-notifications.md)** with [Duo](https://duo.com/).
 * Password reset with identity verification using email confirmation.
 * Single-factor only authentication method available.
 * Access restriction after too many authentication attempts.
@@ -53,7 +53,7 @@ Here is the list of the main available features:
 * Highly-available using distributed database and KV store.
 * Compatible with Kubernetes [ingress-nginx](https://github.com/kubernetes/ingress-nginx) controller out of the box.
 
-For more details about the features, follow [Features](https://github.com/clems4ever/authelia/blob/master/docs/features.md).
+For more details about the features, follow [Features](./docs/features.md).
 
 ## Proxy support
 
@@ -62,9 +62,9 @@ Authelia works in combination with [nginx] or [Traefik] and soon with [HAProxy]
 Docker or directly in [Kubernetes].
 
 <p align="center">
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/nginx.logo.png" height="50"/>
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/traefik.logo.png" height="50"/> 
-  <img src="https://github.com/clems4ever/authelia/raw/master/images/kubernetes.logo.png" height="50"/> 
+  <img src="./docs/images/logos/nginx.logo.png" height="50"/>
+  <img src="./docs/images/logos/traefik.logo.png" height="50"/> 
+  <img src="./docs/images/logos/kubernetes.logo.png" height="50"/> 
 </p>
 
 ## Getting Started
@@ -74,12 +74,12 @@ You can start off with
     git clone https://github.com/clems4ever/authelia.git && cd authelia
     source bootstrap.sh
 
-If you want to go further, please read [Getting Started](https://github.com/clems4ever/authelia/blob/master/docs/getting-started.md).
+If you want to go further, please read [Getting Started](./docs/getting-started.md).
 
 ## Deployment
 
 Now that you have tested **Authelia** and you want to try it out in your own infrastructure,
-you can learn how to deploy and use it with [Deployment](https://github.com/clems4ever/authelia/blob/master/docs/deployment-production.md).
+you can learn how to deploy and use it with [Deployment](./docs/deployment-production.md).
 This guide will show you how to deploy it on bare metal as well as on
 [Kubernetes](https://kubernetes.io/).
 
@@ -87,11 +87,11 @@ This guide will show you how to deploy it on bare metal as well as on
 
 If you want more information about the security measures applied by
 **Authelia** and some tips on how to set up **Authelia** in a secure way,
-refer to [Security](https://github.com/clems4ever/authelia/blob/master/docs/security.md).
+refer to [Security](./docs/security.md).
 
 ## Changelog & Breaking changes
 
-See [CHANGELOG.md](https://github.com/clems4ever/authelia/blob/master/CHANGELOG.md) and [BREAKING.md](https://github.com/clems4ever/authelia/blob/master/BREAKING.md).
+See [CHANGELOG.md](./CHANGELOG.md) and [BREAKING.md](./BREAKING.md).
 
 ## Contribute
 
@@ -104,12 +104,12 @@ I am very grateful to contributors for their contributions to the project. Don't
 
 ## Build Authelia
 
-If you want to contribute with code, you should follow the documentation explaining how to [build](https://github.com/clems4ever/authelia/blob/master/docs/build-and-dev.md) the application.
+If you want to contribute with code, you should follow the documentation explaining how to [build](./docs/build-and-dev.md) the application.
 
 ## License
 
 **Authelia** is **licensed** under the **[Apache 2.0]** license. The terms of the license are detailed
-in [LICENSE](https://github.com/clems4ever/authelia/blob/master/LICENSE).
+in [LICENSE](./LICENSE).
 
 
 [Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0
@@ -118,7 +118,7 @@ in [LICENSE](https://github.com/clems4ever/authelia/blob/master/LICENSE).
 [Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
 [auth_request]: http://nginx.org/en/docs/http/ngx_http_auth_request_module.html
 [Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en
-[config.template.yml]: https://github.com/clems4ever/authelia/blob/master/config.template.yml
+[config.template.yml]: ./config.template.yml
 [nginx]: https://www.nginx.com/
 [Traefik]: https://traefik.io/
 [HAproxy]: http://www.haproxy.org/

README.replaced

@@ -0,0 +1,125 @@
+<p align="center">
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/authelia-title.png" width="350" title="Authelia">
+</p>
+
+  [![license](https://img.shields.io/badge/license-Apache%202.0-green.svg)][Apache 2.0]
+  [![Build](https://travis-ci.org/clems4ever/authelia.svg?branch=master)](https://travis-ci.org/clems4ever/authelia)
+  [![Gitter](https://img.shields.io/gitter/room/badges/shields.svg)](https://gitter.im/authelia/general?utm_source=share-link&utm_medium=link&utm_campaign=share-link)
+
+**Authelia** is an open-source authentication and authorization server
+providing 2-factor authentication and single sign-on (SSO) for your
+applications via a web portal.
+It acts as a companion of reverse proxies like [nginx] or [Traefik] by handling forwarded authentication and authorization requests.
+
+    BREAKING NEWS: Authelia v4 stable release is coming soon! The new version is written in Go for reliability, performance and security improvements. A docker image is currently available in alpha version on dockerhub.
+    Please read BREAKING.md if you want to migrate from v3 to v4. Otherwise, start fresh in v4 and enjoy!
+
+
+<p align="center">
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/logos/authelia.logo.png" height="100"/>
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/plus.png" height="100"/>
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/logos/nginx.logo.png" height="100"/>
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/logos/traefik.logo.png" height="100"/>  
+</p>
+
+**Authelia** can be installed as a standalone service using Docker or NPM
+but can also be deployed easily on [Kubernetes] leveraging ingress controllers and ingress configuration.
+
+<p align="center">
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/logos/kubernetes.logo.png" height="100"/>
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/logos/docker.logo.png" width="100">
+</p>
+
+Here is what Authelia's portal looks like
+
+<p align="center">
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/1FA.png" width="400" />
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/2FA-METHODS.png" width="400" />
+</p>
+
+## Features summary
+
+Here is the list of the main available features:
+
+* Several kind of second factor:
+  * **[Security Key (U2F)](https://github.com/clems4ever/authelia/raw/master/docs/2factor/security-key.md)** with [Yubikey].
+  * **[Time-based One-Time password](https://github.com/clems4ever/authelia/raw/master/docs/2factor/time-based-one-time-password.md)** with [Google Authenticator].
+  * **[Mobile Push Notifications](https://github.com/clems4ever/authelia/raw/master/docs/2factor/duo-push-notifications.md)** with [Duo](https://duo.com/).
+* Password reset with identity verification using email confirmation.
+* Single-factor only authentication method available.
+* Access restriction after too many authentication attempts.
+* Fine-grained access control per subdomain, user, resource and network.
+* Support of basic authentication for endpoints protected by single factor.
+* Highly-available using distributed database and KV store.
+* Compatible with Kubernetes [ingress-nginx](https://github.com/kubernetes/ingress-nginx) controller out of the box.
+
+For more details about the features, follow [Features](https://github.com/clems4ever/authelia/raw/master/docs/features.md).
+
+## Proxy support
+
+Authelia works in combination with [nginx] or [Traefik] and soon with [HAProxy] as discussed in
+[#271](https://github.com/clems4ever/authelia/issues/271). It can be deployed on bare metal with
+Docker or directly in [Kubernetes].
+
+<p align="center">
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/logos/nginx.logo.png" height="50"/>
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/logos/traefik.logo.png" height="50"/> 
+  <img src="https://github.com/clems4ever/authelia/raw/master/docs/images/logos/kubernetes.logo.png" height="50"/> 
+</p>
+
+## Getting Started
+
+You can start off with
+
+    git clone https://github.com/clems4ever/authelia.git && cd authelia
+    source bootstrap.sh
+
+If you want to go further, please read [Getting Started](https://github.com/clems4ever/authelia/raw/master/docs/getting-started.md).
+
+## Deployment
+
+Now that you have tested **Authelia** and you want to try it out in your own infrastructure,
+you can learn how to deploy and use it with [Deployment](https://github.com/clems4ever/authelia/raw/master/docs/deployment-production.md).
+This guide will show you how to deploy it on bare metal as well as on
+[Kubernetes](https://kubernetes.io/).
+
+## Security
+
+If you want more information about the security measures applied by
+**Authelia** and some tips on how to set up **Authelia** in a secure way,
+refer to [Security](https://github.com/clems4ever/authelia/raw/master/docs/security.md).
+
+## Changelog & Breaking changes
+
+See [CHANGELOG.md](./CHANGELOG.md) and [BREAKING.md](./BREAKING.md).
+
+## Contribute
+
+Anybody willing to contribute to the project either with code, 
+documentation, security reviews or whatever, are very welcome to issue
+or review pull requests and take part to discussions in
+[Gitter](https://gitter.im/authelia/general?utm_source=share-link&utm_medium=link&utm_campaign=share-link).
+
+I am very grateful to contributors for their contributions to the project. Don't hesitate, be the next!
+
+## Build Authelia
+
+If you want to contribute with code, you should follow the documentation explaining how to [build](https://github.com/clems4ever/authelia/raw/master/docs/build-and-dev.md) the application.
+
+## License
+
+**Authelia** is **licensed** under the **[Apache 2.0]** license. The terms of the license are detailed
+in [LICENSE](./LICENSE).
+
+
+[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0
+[TOTP]: https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm
+[Security Key]: https://www.yubico.com/about/background/fido/
+[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
+[auth_request]: http://nginx.org/en/docs/http/ngx_http_auth_request_module.html
+[Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en
+[config.template.yml]: ./config.template.yml
+[nginx]: https://www.nginx.com/
+[Traefik]: https://traefik.io/
+[HAproxy]: http://www.haproxy.org/
+[Kubernetes]: https://kubernetes.io/

cmd/authelia-scripts/docker.go

@@ -57,5 +57,5 @@ func (d *Docker) CleanTag(tag string) error {
 
 // PublishReadme push README.md to dockerhub.
 func (d *Docker) PublishReadme() error {
-	return utils.CommandWithStdout("bash", "-c", `jq -n --arg msg "$(<README.md)" '{"registry":"registry-1.docker.io","full_description": $msg }' | curl -fs --retry 3 -o /dev/null -u $DOCKER_USERNAME:$DOCKER_PASSWORD -X "PATCH" -H "Content-Type: application/json" -d @- https://cloud.docker.com/v2/repositories/clems4ever/authelia/`).Run()
+	return utils.CommandWithStdout("bash", "-c", `jq -n --arg msg "$(cat README.md | sed 's/\.\/docs/https:\/\/github.com\/clems4ever\/authelia\/raw\/master\/docs/g')" '{"registry":"registry-1.docker.io","full_description": $msg }' | curl -fs --retry 3 -o /dev/null -u $DOCKER_USERNAME:$DOCKER_PASSWORD -X "PATCH" -H "Content-Type: application/json" -d @- https://cloud.docker.com/v2/repositories/clems4ever/authelia/`).Run()
 }

docs/2factor/duo-push-notifications.md

@@ -1,22 +1,23 @@
 # Duo Push Notification
 
 Using mobile push notifications is becoming the new trendy way to validate
-the second factor of a 2FA authentication process. [Duo](https://duo.com/) is offering an API
-to integrate this kind validation and **Authelia** leverages this mechanism
-so that you can simply push a button on your smartphone to be securely granted
-access to your services.
+the second factor of a 2FA authentication process. [Duo](https://duo.com/)
+is offering an API to integrate this kind validation and **Authelia** leverages
+this mechanism so that you can simply push a button on your smartphone to be
+securely granted access to your services.
 
 <p align="center">
-  <img src="../../images/2factor_duo.png" width="400">
+  <img src="../../docs/images/2FA-PUSH.png" width="400">
 </p>
 
 In order to use this feature, you should first create a free account on Duo
 (up to 10 users), create a user account and attach it a mobile device. The name
-of the user must match the name of the user in your internal database.
-Then, click on *Applications* and *Protect an Application*. Then select the option
-called *Partner Auth API*. This will generate an integration key, a secret key and
-a hostname. You can set the name of the application to **Authelia** and then you
-must add the generated information to your configuration as:
+of the user must match the name of the user in your internal database (LDAP).
+In Duo interface, click on *Applications* and *Protect an Application*. Then
+select the option called *Partner Auth API*. This will generate an integration key,
+a secret key and a hostname. You can set the name of the application to
+**Authelia** and then you must add the generated information to your configuration
+as:
 
     duo_api:
       hostname: api-123456789.example.com
@@ -25,12 +26,12 @@ must add the generated information to your configuration as:
 
 This can be seen in [config.template.yml](../../config.template.yml) file.
 
-When selecting *Duo Push Notification* at the second factor stage, you will
+When selecting *Push Notification* at the second factor stage, you will
 automatically receive a push notification on your phone to grant or deny access.
 
 <p align="center">
-  <img src="../../images/duo-push-1.jpg" width="400">
-  <img src="../../images/duo-push-2.png" width="400">
+  <img src="../../docs/images/duo-push-1.jpg" width="400">
+  <img src="../../docs/images/duo-push-2.png" width="400">
 </p>
 
 ## Limitations
@@ -41,7 +42,7 @@ Users must be enrolled via the Duo Admin panel, they cannot enroll a device from
 
 ## FAQ
 
-### Why don't I have access to the *Duo Push Notification* option?
+### Why don't I have access to the *Push Notification* option?
 
 It's likely that you have not configured **Authelia** correctly. Please read this
 documentation again and be sure you had a look at [config.template.yml](../../config.template.yml).

docs/2factor/security-key.md

@@ -1,30 +1,30 @@
 # Security Keys (U2F)
 
-**Authelia** also offers authentication using Security Keys supporting U2F
-like [Yubikey](Yubikey) USB devices. U2F is one of the most secure
-authentication protocol and is already available for Google, Facebook, Github
-accounts and more.
+**Authelia** offers authentication using Security Keys like [Yubikey](Yubikey)
+which are one of the most secure way to authenticate and get authorized.
+It is already available for Google, Facebook, Github accounts and more.
 
-The protocol requires your security key being enrolled before authenticating.
+The protocol requires your security key to enrolled before authenticating.
 
-<p align="center">
-  <img src="../../images/2factor_u2f.png" width="400">
-</p>
+To do so, select the *Security Key* method at the second factor stage and
+click on the link *Not registered yet?*. This will send a link to your 
+user email address. This e-mail will likely be sent to
+https://mail.example.com:8080/ if you're testing Authelia and you've not
+configured anything.
 
-To do so, select the *Security Key* method in the second factor page and click
-on the *register new device* link. This will send a link to the 
-user email address. This e-mail will likely be sent to https://mail.example.com:8080/
-if you're testing Authelia and you've not configured anything.
-
-Confirm your identity by clicking on **Continue** and you'll be asked to
+Confirm your identity by clicking on **Register** and you'll be asked to
 touch the token of your security key to enroll.
 
 <p align="center">
-  <img src="../../images/u2f.png" width="400">
+  <img src="../../docs/images/REGISTER-U2F.png" width="400">
 </p>
 
-Upon successful registration, you can authenticate using your security key by simply
-touching the token again.
+Upon successful registration, you can authenticate using your security key
+by simply touching the token again when required:
+
+<p align="center">
+  <img src="../../docs/images/2FA-U2F.png" width="400">
+</p>
 
 Easy, right?!
 
@@ -32,9 +32,9 @@ Easy, right?!
 
 ### Why don't I have access to the *Security Key* option?
 
-U2F protocol is a new protocol that is only supported by recent browser
-and must even be enabled on some of them like Firefox. Please be sure
-your browser supports U2F and that the feature is enabled to make the
-option available in **Authelia**.
+U2F protocol is a new protocol that is only supported by recent browsers
+and might even be enabled on some of them. Please be sure your browser
+supports U2F and that the feature is enabled to make the option
+available in **Authelia**.
 
 [Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/

docs/2factor/time-based-one-time-password.md

@@ -4,25 +4,25 @@ In **Authelia**, your users can use [Google Authenticator] for generating unique
 tokens that they can use to pass the second factor.
 
 <p align="center">
-  <img src="../../images/2factor_totp.png" width="400">
+  <img src="../../docs/images/2FA-TOTP.png" width="400">
 </p>
 
-Select the *One-Time Password method* and click on the *register new device* link.
+Select the *One-Time Password method* and click on the *Not registered yet?* link.
 Then, check the email sent by **Authelia** to your email address
 to validate your identity. If you're testing **Authelia**, it's likely
 that this e-mail has been sent to https://mail.example.com:8080/
 
-Confirm your identity by clicking on **Continue** and you'll get redirected
-on a page where your secret will be displayed as QRCode and in Base32 formats.
+Confirm your identity by clicking on **Register** and you'll get redirected
+on a page where your secret will be displayed as QRCode that you can scan.
 
 <p align="center">
-  <img src="../../images/totp.png" width="400">
+  <img src="../../docs/images/REGISTER-TOTP.png" width="400">
 </p>
 
 You can use [Google Authenticator] to store it.
 
-From now on, you'll get generated
-tokens from your phone that you can use to validate the second factor in **Authelia**.
+From now on, you'll get tokens generated every 30 seconds on your phone that
+you can use to validate the second factor in **Authelia**.
 
 
 

docs/authelia-scripts.md

@@ -12,10 +12,14 @@ Then, you can access the scripts usage by running the following command:
 
     authelia-scripts --help
 
-For instance, you can build Authelia with:
+For instance, you can build Authelia (Go binary and frontend) with:
 
     authelia-scripts build
 
+Or build the official Docker image with:
+
+    authelia-scripts docker build
+
 Or start the *Standalone* suite with:
 
     authelia-scripts suites setup Standalone

docs/build-and-dev.md

@@ -1,53 +1,83 @@
 # Build and dev
 
-**Authelia** is written in Go and comes with a dedicated CLI called [authelia-scripts](./authelia-scripts.md)
-which is available after running `source bootstrap.sh`. This CLI provides many useful tools to help you during
-development.
+**Authelia** is written in Go and comes with a dedicated CLI called
+[authelia-scripts](./authelia-scripts.md) which is available after
+running `source bootstrap.sh`. This CLI provides many useful tools
+to help you during development.
 
-In order to build and contribute to **Authelia**, you need to make sure Go v1.13, Docker,
-docker-compose and Node with version >= 8 and < 12 are installed on your machine.
+In order to build and contribute to **Authelia**, you need to make
+sure Go v1.13, Docker, docker-compose and Node v12 are installed on
+your machine.
 
 ## Get started
 
-**Authelia** is made of Go application serving the API and a [React](https://reactjs.org/)
-application for the portal.
+**Authelia** is made of Go application serving the API and a
+[React](https://reactjs.org/) application for the portal.
 
-In order to ease development, Authelia uses the concept of [suites] to run Authelia from source
-code so that your patches are included. This is a kind of virtual environment running **Authelia**
-in a complete ecosystem (LDAP, Redis, SQL server). Note that Authelia is hotreloaded in the
-environment so that your patches are instantly included.
+In order to ease development, Authelia uses the concept of [suites] to
+run Authelia from source code so that your patches are included. This
+is a kind of virtual environment running **Authelia** in a complete
+ecosystem (LDAP, Redis, SQL server). Note that Authelia is hotreloaded
+in the environment so that your patches are instantly included.
 
 The next command starts the suite called *Standalone*:
 
-    authelia-scripts suites setup Standalone
+    $ authelia-scripts suites setup Standalone
 
-Most of the suites are using docker-compose to bootstrap the environment. Therefore, you
-can check the logs of all application by running the following command on the component
-you want to monitor.
+Most of the suites are using docker-compose to bootstrap the
+environment. Therefore, you can check the logs of all application
+by running the following command on the component you want to
+monitor.
 
-    docker logs authelia_authelia-backend_1 -f
+    $ docker logs authelia_authelia-backend_1 -f
 
-Then, edit the code and observe how **Authelia** is automatically reloaded.
+Then, edit the code and observe how **Authelia** is automatically
+reloaded.
 
 ### Unit tests
 
 To run the unit tests, run:
 
-    authelia-scripts unittest
+    $ authelia-scripts unittest
 
 ### Integration tests
 
-Integration tests are located under the `suites` directory based on Selenium.
+Integration tests are located under the `internal/suites` directory
+and are based on Selenium. A suite is a combination of environment
+and tests. Executing a suite therefore means starting the environment,
+running the tests and tearing down the environment. Each step can be
+run independantly:
 
-    authelia-scripts suites test
+    # List the available suites
+    $ authelia-scripts suites list
+    Standalone
+    DuoPush
+    LDAP
+    Traefik
 
-You don't need to start the suite before testing it. Given you're not running
-any suite, just use the following command to test the *Standalone* suite.
+    # Start the environment of Standalone suite.
+    $ authelia-scripts suites setup Standalone
 
-    authelia-scripts suites test Standalone
+    # Run the tests related to the currently running suite.
+    $ authelia-scripts suites test
 
-The suite will be spawned, tests will be run and then the suite will be teared down
-automatically.
+    # Tear down the environment
+    $ authelia-scripts suites teardown Standalone
+
+
+In order to test all suites (approx 30 minutes), you need to make
+sure there is no currently running suite and then you should run:
+
+    $ authelia-scripts suites test
+
+Also, you don't need to start the suite before testing it. Given
+you're not running any suite, just use the following command to
+test the *Standalone* suite.
+
+    $ authelia-scripts suites test Standalone
+
+The suite will be spawned, tests will be run and then the suite
+will be teared down automatically.
 
 
 [suites]: ./suites.md

docs/configuration.md

@@ -1,11 +1,12 @@
 # Configuration
 
 Authelia is highly configurable thanks to a configuration file. 
-There is a documented template configuration, called [config.template.yml](./config.template.yml), at
-the root of the repository. All the details are documented there.
+There is a documented template configuration, called
+[config.template.yml](./config.template.yml), at the root of the
+repository. All the details are documented there.
 
 When running **Authelia**, you can specify your configuration file by passing
 the file path as the first argument of **Authelia**.
 
-    authelia config.custom.yml
+    $ authelia -config config.custom.yml
 

docs/deployment-dev.md

@@ -16,8 +16,8 @@ non resilient to failures.*
 **NOTE:** If not done already, we highly recommend you first follow the
 [Getting Started] documentation.
 
-In some cases, like protecting personal projects/websites, it can be fine to use
-**Authelia** in a non highly-available setup. This reduces the number
+In some cases, like protecting personal projects/websites, it can be fine
+to use **Authelia** in a non highly-available setup. This reduces the number
 of components to only two: a reverse proxy such as nginx or Traefik and
 Authelia as a companion of the proxy.
 
@@ -26,17 +26,18 @@ either by pulling the Docker image or building distributable version.
 
 ## Build and deploy the distributable version
 
-    authelia-scripts build
-    PUBLIC_DIR=./dist/public_html ./dist/authelia -config /path/to/your/config.yml
+    $ authelia-scripts build
+    $ PUBLIC_DIR=./dist/public_html ./dist/authelia -config /path/to/your/config.yml
 
 ## Deploy with Docker
 
-    docker pull clems4ever/authelia
-    docker run -v /path/to/your/config.yml:/etc/authelia/config.yml clems4ever/authelia
+    $ docker pull clems4ever/authelia
+    $ docker run -v /path/to/your/config.yml:/etc/authelia/config.yml clems4ever/authelia
 
 ## Deploy Nginx
 
-You also need to install nginx and take [example/compose/nginx/minimal/nginx.conf](./example/compose/nginx/minimal/nginx.conf)
+You also need to install nginx and take
+[example/compose/nginx/minimal/nginx.conf](./example/compose/nginx/minimal/nginx.conf)
 as an example for your configuration.
 
 ## Deploy Traefik
@@ -47,11 +48,12 @@ TODO
 
 ### Discard SQL server
 
-There is an option in the configuration file to avoid using an external SQL server
-and use a local sqlite3 database instead. This option will therefore prevent you
-from running multiple instances of **Authelia** in parallel.
-Consequently, this option is not meant to be used in production or at least
-not one that should scale out.
+There is an option in the configuration file to avoid using an external
+SQL server and use a local sqlite3 database instead. This option will
+therefore prevent you from running multiple instances of **Authelia**
+in parallel.
+Consequently, this option is not meant to be used in production or at
+least not one that should scale out.
 
 Here is the configuration you should use:
 
@@ -88,8 +90,8 @@ from running multiple instances of **Authelia** in parallel and is therefore
 discouraged for production environments.
 
 To use a file backend instead of a LDAP server, you should first duplicate
-the file [users_database.yml](../test/suites/basic/users_database.yml) and edit it to add the
-users you want.
+the file [users_database.yml](../test/suites/basic/users_database.yml) and
+edit it to add the users you want.
 
 The content of this file is as follows:
 
@@ -106,7 +108,7 @@ The password is hashed and salted as it is in LDAP servers with salted SHA-512
 (more hash algorithms such as Argon2 will be provided in the future).
 Here is a one-liner to generate such hashed password:
 
-    $ authelia-scripts hash-password mypassword
+    $ 
     $6$rounds=50000$BpLnfgDsc2WD8F2q$PumMwig8O0uIe9SgneL8Cm1FvUniOzpqBrH.uQE3aZR4K1dHsQldu5gEjJZsXcO./v3itfz6CXTDTJgeh5e8t.
 
 Copy this newly hashed password into your `users_database.yml` file, prefixed with

docs/deployment-production.md

@@ -31,18 +31,17 @@ the root of the repo.
 ### Deploy with the distributable version
 
     # Build it if not done already
-    authelia-scripts build
-
-    PUBLIC_DIR=./dist/public_html authelia -config /path/to/your/config.yml
+    $ authelia-scripts build
+    $ PUBLIC_DIR=./dist/public_html authelia -config /path/to/your/config.yml
 
 ### Deploy With Docker
 
-    docker run -v /path/to/your/config.yml:/etc/authelia/config.yml -e TZ=Europe/Paris clems4ever/authelia
+    $ docker run -v /path/to/your/config.yml:/etc/authelia/config.yml -e TZ=Europe/Paris clems4ever/$ $ authelia -config /etc/authelia/config.yml
 
 
 ## On top of Kubernetes
 
-<img src="../images/kubernetes.logo.png" width="50" style="padding-right: 10px" align="left">
+<img src="../docs/images/logos/kubernetes.logo.png" width="50" style="padding-right: 10px" align="left">
 
 **Authelia** can also be installed on top of [Kubernetes] using
 [nginx ingress controller](https://github.com/kubernetes/ingress-nginx).

docs/features.md

@@ -1,6 +1,6 @@
 # Features in details
 
-## First factor using a LDAP server
+## 1-Factor (1FA) using a LDAP server
 
 **Authelia** uses an LDAP server as the backend for storing credentials.
 When authentication is needed, the user is redirected to the login page which
@@ -11,11 +11,11 @@ You can find an example of the configuration of the LDAP backend in
 [config.template.yml].
 
 <p align="center">
-  <img src="../images/first_factor.png" width="400">
+  <img src="../docs/images/1FA.png" width="400">
 </p>
 
 
-## Second factor
+## 2-Factor (2FA)
 
 **Authelia** comes with three kind of second factor.
 
@@ -24,7 +24,7 @@ You can find an example of the configuration of the LDAP backend in
 * Duo Push Notifications to use with [Duo mobile application](https://play.google.com/store/apps/details?id=com.duosecurity.duomobile&hl=en) available on Android, iOS and Windows. More info [here](./2factor/duo-push-notifications.md).
 
 <p align="center">
-  <img src="../images/use-another-method.png" width="400">
+  <img src="../docs/images/2FA-METHODS.png" width="400">
 </p>
 
 ## Password reset
@@ -37,7 +37,7 @@ email to the user email address.
 Proceed with the password reset form and validate to reset your password.
 
 <p align="center">
-  <img src="../images/reset_password.png" width="400">
+  <img src="../docs/images/RESET-PASSWORD-STEP1.png" width="400">
 </p>
 
 ## Access Control
@@ -63,7 +63,7 @@ Please note that Authelia uses the *Proxy-Authorization* header and not
 Authelia and the proxy. For instance you can use the following command to
 access your service:
 
-    curl -H "Proxy-Authorization: Basic am9objpwYXNzd29yZA==" https://myservice.example.com"
+    $ curl -H "Proxy-Authorization: Basic am9objpwYXNzd29yZA==" https://myservice.example.com"
 
 ## Session management with Redis
 

docs/getting-started.md

@@ -5,11 +5,11 @@
 In order to deploy the current version of Authelia locally, run the following
 command and follow the instructions of bootstrap.sh:
 
-    source bootstrap.sh
+    $ source bootstrap.sh
 
 Then, start the *Standalone* [suite].
 
-    authelia-scripts suites setup Standalone
+    $ authelia-scripts suites setup Standalone
 
 A [suite] is kind of a virtual environment for running Authelia in a complete ecosystem.
 If you want more details please read the related [documentation](./suites.md).
@@ -28,20 +28,21 @@ normal to see this exception several times.
 Below is what the login page looks like after you accepted all exceptions:
 
 <p align="center">
-  <img src="../images/first_factor.png" width="400">
+  <img src="../docs/images/1FA.png" width="400">
 </p>
 
-You can use one of the users listed in [https://home.example.com:8080/](https://home.example.com:8080/).
+You can use one of the users listed in
+[https://home.example.com:8080/](https://home.example.com:8080/).
 The rights granted to each user and group is also provided in the page as
 a list of rules.
 
 At some point, you'll be required to register your second factor device.
 Since your security is **Authelia**'s priority, it will send 
 an email to the email address of the user to confirm the user identity.
-Since we're running a test environment, we provide a fake webmail called
-*MailCatcher* from which you can checkout the email and confirm
-your identity.
-The webmail is accessible from
+Since you are running a test environment, a fake webmail called
+*MailCatcher* has been deployed for you to check out the email and
+confirm your identity.
+The webmail is accessible at
 [http://mail.example.com:8080](http://mail.example.com:8080).
 
 Enjoy!
@@ -60,7 +61,7 @@ Here are the versions used for testing in Travis:
 
 ### How am I supposed to access the subdomains of example.com?
 
-Well, in order to test Authelia, Authelia fakes your browser by adding entries
+In order to test Authelia, Authelia fakes your browser by adding entries
 in /etc/hosts when you first source the bootstrap.sh script.
 
 ### What should I do if I want to contribute?

docs/security.md

@@ -2,7 +2,7 @@
 
 ## Protection against cookie theft
 
-Authelia uses two mechanism to protect against cookie theft:
+Authelia uses two mechanisms to protect against cookie theft:
 1. session attribute `httpOnly` set to true make client-side code unable to
 read the cookie.
 2. session attribute `secure` ensure the cookie will never be sent over an
@@ -21,14 +21,6 @@ that the attacker must also require the certificate to retrieve the cookies.
 Note that using [HSTS] has consequences. That's why you should read the blog
 post nginx has written on [HSTS].
 
-## Content-Security-Policy
-
-Authelia's portal is protected against some XSS using the content
-security policy mechanism that is documented
-[here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). This protection
-will reject untrusted payloads threatening your users during the authentication
-workflow.
-
 ## More protections measures with Nginx
 
 You can also apply the following headers to your nginx configuration for

docs/suites.md

@@ -1,46 +1,39 @@
 # Suites
 
-Authelia is a single component in interaction with many others. Consequently, testing the features
-is not as easy as we might think. In order to solve this problem, Authelia came up with the concept of
-suite which is a kind of virtual environment for Authelia, it allows to create an environment made of
-components such as nginx, redis or mariadb in which Authelia can run and be tested.
+Authelia is a single component in interaction with many others in a complete
+ecosystem. Consequently, testing the features is not as easy as we might
+think. In order to solve this problem, Authelia came up with the concept of
+suite which is a kind of virtual environment for Authelia and a set of tests.
+A suite can setup components such as nginx, redis or mariadb in which
+Authelia can run and be tested.
 
-This abstraction allows to prepare an environment for manual testing during development and also to
-craft and run integration tests efficiently.
+This abstraction allows to prepare an environment for manual testing during
+development and also to craft and run integration tests efficiently.
 
 ## Start a suite.
 
 Starting a suite called *Standalone* is done with the following command:
 
-    authelia-scripts suites setup Standalone
+    $ authelia-scripts suites setup Standalone
 
-It will deploy the environment of the suite and block until you hit ctrl-c to stop the suite.
+This command deploys the environment of the suite.
 
 ## Run tests of a suite
 
 ### Run tests of running suite
 
-If a suite is already running, you can simply type:
+If a suite is already running, you can simply type the test command
+that will run the test related to the currently running suite:
 
-    authelia-scripts suites test
-
-and this will run the tests related to the running suite.
+    $ authelia-scripts suites test
 
 ### Run tests of non-running suite
 
-However, if no suite is running and you still want to test a particular suite like *HighAvailability*.
-You can do so with the next command:
+However, if no suite is running yet and you just want to run the tests of a
+specific suite like *HighAvailability*, you can do so with the next command:
 
-    authelia-scripts suites test HighAvailability
-
-This command will run the tests for the *HighAvailability* suite. Beware that running tests of a
-non-running suite implies the tests run against the distributable version of Authelia instead of
-the current development version. If you made some patches, you must build the distributable version
-before running the test command:
-
-    # Build authelia before running the tests against the suite.
-    authelia-scripts build
-    authelia-scripts docker build
+    # Set up the env, run the tests and tear down the env
+    $ authelia-scripts suites test HighAvailability
 
 ### Run all tests of all suites
 
@@ -48,26 +41,25 @@ Running all tests is easy. Make sure that no suite is already running and run:
 
     authelia-scripts suites test
 
-Beware that the distributable version of Authelia is tested in that case. Don't
-forget to build Authelia including your patches before running the command.
-
-
-    # Build authelia before running the tests against the suite.
-    authelia-scripts build
-    authelia-scripts docker build
-
 ### Run tests in headless mode
 
-In order to run the tests in headless mode, use the following command:
+As you might have noticed, the tests are run using chromedriver and selenium. It means
+that the tests open an instance of Chrome that might interfere with your other activities.
+In order to run the tests in headless mode to avoid the interference, use the following
+command:
 
-    authelia-scripts suites test --headless
+    $ authelia-scripts suites test --headless
 
 
 ## Create a suite
 
-Creating a suite is as easy as creating a new directory with at least two files:
+Creating a suite is as easy. Let's take the example of the **Standalone** suite:
 
-* **environment.ts** - It defines the setup and teardown phases when creating the environment. The *setup*
-phase is the phase when the required components will be spawned and Authelia will start while the *teardown*
-is executed when the suite is destroyed (ctrl-c hit by the user) or the tests are finished.
-* **test.ts** - It defines a set of tests to run against the suite.
+* **suite_standalone.go** - It defines the setup and teardown phases. It likely uses
+docker-compose to setup the ecosystem. This file also defines the timeouts.
+* **suite_standalone_test.go** - It defines the set of tests to run against the suite.
+* **Standalone** directory - It contains resources required by the suite and likely
+mounted in the containers.
+
+A suite can also be much more complex like setting up a complete Kubernetes ecosystem.
+You can check the Kubernetes suite as example.