Update the documentation to include info about suites and authelia-scripts.

docs/authelia-scripts.md

@@ -0,0 +1,20 @@
+# Authelia Scripts
+
+Authelia comes with a set of dedicated scripts doing a broad range of operations such as
+building the distributed version of Authelia, building the Docker image, running suites,
+testing the code, etc...
+
+You can access the scripts usage by running the following command:
+
+    npm run scripts
+
+For instance, you can build Authelia with:
+
+    npm run scripts build
+
+Or start the *basic* suite with:
+
+    npm run scripts suites start basic
+
+
+You will find more information in the scripts usage helpers.

docs/build.md

@@ -1,73 +1,53 @@
 # Build
 
-**Authelia** is written in Typescript and built with [Grunt](https://gruntjs.com/).
+**Authelia** is written in Typescript and built with [Authelia scripts](docs/authelia-scripts.md).
 
-In order to build **Authelia**, you need to make sure Node v8 and NPM is
+In order to build **Authelia**, you need to make sure Node with version >= 8 and < 10 and NPM is
 installed on your machine.
 
-Then, run the following command install the node modules:
+Then, run the following command to install the node modules:
 
     npm install
 
 And, this command to build **Authelia** under dist/:
 
-    ./node_modules/.bin/grunt build
+    npm run build
+
+Then you can also build the Docker image with:
+
+    npm run docker build
 
 ## Details
 
 ### Build
 
-**Authelia** is made of two components: the client and the server.
+**Authelia** is made of two parts: the frontend and the backend.
 
-The client is written in Typescript and uses jQuery. It is built as part of
+The frontend is a [React](https://reactjs.org/) application written in Typescript and
-the global `build` Grunt command.
+the backend is an express application also written in Typescript.
-
-The server is written in Typescript. It is also built as part of the global `build`
-Grunt command.
 
 ### Tests
 
-Grunt also handles the commands to run the tests. There are several type of
+There are two kind of tests: unit tests and integration tests.
-tests for **Authelia**: unit tests for the server, the client and a shared
-library and an integration test suite testing both components together.
-
-The unit tests are written with Mocha while integration tests are using
-Cucumber and Mocha.
 
 ### Unit tests
 
-To run the client unit tests, run:
+To run the unit tests, run:
 
-    ./node_modules/.bin/grunt test-client
+    npm run unittest
-
-To run the server unit tests, run:
-
-    ./node_modules/.bin/grunt test-server
-
-To run the shared library unit tests, run:
-
-    ./node_modules/.bin/grunt test-shared
 
 ### Integration tests
 
-Integration tests are mainly based on Selenium so they
+Integration tests run with Mocha and are based on Selenium. They generally
-need a complete environment to be run.
+require a complete environment made of several components like redis, mongo and a LDAP
+to run.
 
-You can start by making sure **Authelia** is built with:
+In order to simplify the creation of such environments, Authelia comes with a concept of
+[Suites] that basically act as virtual environments for running either
+manual or integration tests.
 
-    grunt build
+Please read the documentation related to [Suites] in order to discover
+how to run related tests.
 
-and the docker image is built with:
 
-    ./scripts/example-commit/dc-example.sh build
+[Suites]: ./suites.md
-
-Then, start the environment with:
-
-    ./scripts/example-commit/dc-example.sh up -d
-
-And run the tests with:
-
-    ./node_modules/.bin/grunt test-int
-
-Note: the Cucumber tests are hard to maintain and will therefore
-be refactored to use Mocha instead.

docs/deployment-dev.md

@@ -17,9 +17,9 @@ non resilient to failures.*
 [Getting Started] documentation.
 
 In some cases, like protecting personal websites, it can be fine to use
-**Authelia** in a non highly-available manner. Fortunately, we can
+**Authelia** in a non highly-available setup. We can
-achieve to run it along with one reverse proxy meaning the setup is
+achieve that in order to reduce the number of components to only two: Authelia
-then reduced to only two components: Authelia and nginx.
+and nginx.
 
 As for a regular deployment in production, you need to install **Authelia**
 either by pulling the Docker image or installing the npm package and run
@@ -37,7 +37,8 @@ it with a configuration file passed as argument.
 
 ## Deploy Nginx
 
-You also need to install nginx and take [example/compose/nginx/minimal/nginx.conf](./example/compose/nginx/minimal/nginx.conf) as an example of configuration.
+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.
 
 ## Discard components
 
@@ -83,7 +84,7 @@ 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](../users_database.yml) and edit it to add the
+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:
@@ -99,10 +100,10 @@ The content of this file is as follows:
 
 The password is hashed and salted as it is in LDAP servers with salted SHA-512. Here is a one-liner to generate such hashed password:
 
-    python3 -c 'import crypt; print("{CRYPT}" + crypt.crypt("mypassword", crypt.mksalt(crypt.METHOD_SHA512, rounds=500000)))'
+    npm run hash-password mypassword
 
 Once the file is created, edit the configuration file with the following
-block (as used in [config.minimal.yml](../config.minimal.yml)):
+block (as used in [config.yml](../test/suites/basic/config.yml)):
 
     authentication_backend:
       file:
@@ -141,9 +142,13 @@ crash or an hardware issue. Moreover, it will also prevent from reliably
 persisting data and consequently fail access to your platform as the devices
 registered by your users will be lost.
 
-### Why is this not automated?
+### Why aren't all those steps automated?
 
 Well, as stated before those instructions are not meant to be applied for
 a production environment. That being said, in some cases it is just fine and
-so writing an Ansible playbook to automate all this process would be great.
+writing an Ansible playbook to automate all this process is ok.
 We would really be more than happy to review such a PR.
+In the meantime, you can check the *basic* [suite](./suites.md) to see all this
+in real example.
+
+[Getting Started]: ./getting-started.md

docs/deployment-production.md

@@ -36,17 +36,12 @@ the root of the repo.
 
 <img src="/images/kube-logo.png" width="24" align="left">
 
-**Authelia** can also be used on top of [Kubernetes] using [nginx ingress
+**Authelia** can also be used on top of [Kubernetes] using
-controller](https://github.com/kubernetes/ingress-nginx).
+[nginx ingress controller](https://github.com/kubernetes/ingress-nginx).
 
 Please refer to the following [documentation](../example/kube/README.md)
 for more information.
 
-[config.template.yml]: ../config.template.yml
-[Getting Started]: ./getting-started.md
-[Deployment for Devs]: ./deployment-dev.md
-[Kubernetes]: https://kubernetes.io/
-
 ## FAQ
 
 ### Why is this not automated?
@@ -55,4 +50,11 @@ Ansible would be a very good candidate to automate the installation of such
 an infrastructure on bare metal. We would be more than happy to review any PR on that matter.
 
 Regarding Kubernetes, the right way to go would be to write a helm recipe.
-Again, we would be glad to review any PR implementing this.
+Again, we would be glad to review any PR implementing this.
+
+
+
+[config.template.yml]: ../config.template.yml
+[Getting Started]: ./getting-started.md
+[Deployment for Devs]: ./deployment-dev.md
+[Kubernetes]: https://kubernetes.io/

docs/getting-started.md

@@ -26,16 +26,17 @@ Here are the versions used for testing in Travis:
 
 Make sure you don't have anything listening on port 8080 and 8085.
 
-The port 8080 will be our frontend load balancer serving both **Authelia**'s portal and the applications we want to protect.
+The port 8080 will be our frontend load balancer serving both **Authelia**'s portal and the
+applications we want to protect.
 
-The port 8085 is serving a webmail used to receive fake emails sent by **Authelia**
+The port 8085 is serving a webmail used to receive emails sent by **Authelia**
 to validate your identity when registering U2F or TOTP secrets or when
 resetting your password.
 
 ### Subdomain aliases
 
-In order to simulate the behavior of a DNS resolving some test subdomains of **example.com** to your machine, we
+In order to simulate the behavior of a DNS resolving some test subdomains of **example.com**
-need to add the following lines to your **/etc/hosts**. It will alias the
+to your machine, we need to add the following lines to your **/etc/hosts**. It will alias the
 subdomains so that nginx can redirect requests to the correct virtual host.
 
     127.0.0.1       home.example.com
@@ -52,7 +53,10 @@ subdomains so that nginx can redirect requests to the correct virtual host.
 To deploy **Authelia** using the latest image from [Dockerhub], run the
 following command:
 
-    ./scripts/example-dockerhub/deploy-example.sh
+    npm run script suites start dockerhub
+
+A Suites is a virtual environment for running Authelia. If you want more details please
+read the related [documentation](./suites.md).
 
 ## Test it!
 
@@ -71,8 +75,8 @@ Below is what the login page looks like after you accepted all exceptions:
   <img src="../images/first_factor.png" width="400">
 </p>
 
-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
+You can use one of the users listed in [https://home.example.com:8080/](https://home.example.com:8080/).
-group is also provided there.
+The rights granted to each user and group is also provided there.
 
 At some point, you'll be required to register your second factor, either
 U2F or TOTP. Since your security is **Authelia**'s priority, it will send 
@@ -86,8 +90,8 @@ The webmail is accessible from
 **Note:** If you cannot deploy the fake webmail for any reason. You can
 configure **Authelia** to use the filesystem notifier (option available
 in [config.template.yml]) that will send the content of the email in a
-file instead of sending an email. It is advised to use this option
+file instead of sending an email. It is advised to not use this option
-for testing only.
+in production.
 
 Enjoy!
 

docs/security.md

@@ -21,6 +21,14 @@ 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 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

@@ -0,0 +1,55 @@
+# Suites
+
+Authelia is a single component in interaction with many others. Consequently, testing the features
+is not as easy as we might think. Consequently, a suite is kind of a virtual environment for Authelia, 
+it allows to create an environment made of components such as nginx, redis or mongo 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.
+
+## Start a suite.
+
+Starting a suite called *simple* is done with the following command:
+
+    npm run scripts suites start simple
+
+It will start the suite and block until you hit ctrl-c to stop the suite.
+
+## Run tests of a suite
+
+### Run tests of running suite
+
+If you are already running a suite with the previous command, you can simply type:
+
+    npm run scripts test
+
+and this will run the tests related to the running suite.
+
+### Run tests of non-running suite
+
+However, if no suite is running and you still want to test a particular suite like *complete*.
+You can do so with the next command:
+
+    npm run scripts test complete
+
+This command will run the tests for the *complete* suite using the built version of Authelia that
+should be located in *dist*.
+
+WARNING: Authelia must be built before running this command.
+
+### Run all tests of all suites
+
+Running all tests is as easy as making sure that there is no running suite and typing:
+
+    npm run scripts test
+
+
+## Create a suite
+
+Creating a suite is as easy as creating a new directory with at least two files:
+
+* **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).
+* **test.ts** - It defines a set of tests to run in the virtual environment of the suite.

package.json

@@ -15,7 +15,8 @@
     "test": "./scripts/authelia-scripts suites test",
     "travis": "./scripts/authelia-scripts travis",
     "cover": "NODE_ENV=test nyc npm t",
-    "scripts": "./scripts/authelia-scripts"
+    "scripts": "./scripts/authelia-scripts",
+    "hash-password": "./scripts/authelia-scripts hash-password"
   },
   "repository": {
     "type": "git",

test/suites/README.md

@@ -1,55 +1,5 @@
 # Authelia Suites
 
-Authelia is a single component in interaction with many others. Consequently, testing the features
+A **suite** is a kind of virtual environment for Authelia. Please
-is not as easy as we might think. Consequently, a suite is kind of a virtual environment for Authelia, 
+read the related documentation [here](../docs/suites.md) to get more
-it allows to create an environment made of components such as nginx, redis or mongo in which Authelia can
+details.
-run and be tested.
-
-This abstraction allows to prepare an environment for manual testing during development and also to
-craft and run integration tests.
-
-## Start a suite.
-
-Starting a suite called *simple* is done with the following command:
-
-    npm run scripts suites start simple
-
-It will start the suite and block until you hit ctrl-c to stop the suite.
-
-## Run tests of a suite
-
-### Run tests of running suite
-
-If you are already running a suite with the previous command, you can simply type:
-
-    npm run scripts test
-
-and this will run the tests related to the running suite.
-
-### Run tests of non-running suite
-
-However, if no suite is running and you still want to test a particular suite like *complete*.
-You can do so with the next command:
-
-    npm run scripts test complete
-
-This command will run the tests for the *complete* suite using the built version of Authelia that
-should be located in *dist*.
-
-WARNING: Authelia must be built before running this command.
-
-### Run all tests of all suites
-
-Running all tests is as easy as making sure that there is no running suite and typing:
-
-    npm run scripts test
-
-
-## Create a suite
-
-Creating a suite is as easy as creating a new directory with at least two files:
-
-* **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).
-* **test.ts** - It defines a set of tests to run in the virtual environment of the suite.