diff --git a/README.md b/README.md
index 748a4656..59107576 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,14 @@ For more details about the features, follow [Features](./docs/features.md).
## Getting Started
-Follow [Getting Started](./docs/getting-started.md).
+If you want to quickly test Authelia with Docker, we recommend you 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](./docs/deployment-production.md). This guide will show you how to deploy
+it on bare metal as well as on Kubernetes.
## Security
@@ -49,15 +56,6 @@ 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](./docs/security.md).
-## Deployment
-
-To learn how to deploy **Authelia** or use it on Kubernetes, please follow
-[Deployment](./docs/deployment.md).
-
-## Build Authelia
-
-Follow [Build](./docs/build.md).
-
## Changelog
See [CHANGELOG.md](CHANGELOG.md).
@@ -71,6 +69,11 @@ or review pull requests and take part to discussions in
We are already greatful to contributors listed in
[CONTRIBUTORS.md](CONTRIBUTORS.md) for their contributions to the project.
+Be the next in the list!
+
+## Build Authelia
+
+If you want to contribute with code, you should follow the documentation explaining how to [build](./docs/build.md) the application.
## Donation
diff --git a/docs/build.md b/docs/build.md
index ca564f42..9437d1f6 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -1,6 +1,6 @@
# Build
-**Authelia** is written in Typescript and built with Grunt.
+**Authelia** is written in Typescript and built with [Grunt](https://gruntjs.com/).
In order to build **Authelia**, you need to make sure Node v8 and NPM is
installed on your machine.
@@ -22,14 +22,14 @@ And, this command to build **Authelia** under dist/:
The client is written in Typescript and uses jQuery. It is built as part of
the global `build` Grunt command.
-The server is written in Typescript. It is built as part of the global `build`
+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
-tests for **Authelia**: unit tests for the server, unit tests for the client
-and integration tests for both.
+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.
@@ -44,12 +44,16 @@ 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
-need a complete environment to be set up.
+need a complete environment to be run.
-Start by making sure **Authelia** is built with:
+You can start by making sure **Authelia** is built with:
grunt build
diff --git a/docs/configuration.md b/docs/configuration.md
index 4c3f43fb..4fafa798 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,7 +1,7 @@
# Configuration
Authelia is highly configurable thanks to a configuration file.
-There is a documented template configuration, called [config.template.yml], at
+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
diff --git a/docs/deployment-dev.md b/docs/deployment-dev.md
new file mode 100644
index 00000000..fbfd48fa
--- /dev/null
+++ b/docs/deployment-dev.md
@@ -0,0 +1,149 @@
+# Deployment for Dev
+
+1. [Deploy With npm](#deploy-with-npm)
+2. [Deploy With Docker](#deploy-with-docker)
+3. [Deploy nginx](#deploy-nginx)
+4. [Discard components](#discard-components)
+ 1. [Discard MongoDB](#discard-mongodb)
+ 2. [Discard Redis](#discard-redis)
+ 3. [Discard LDAP](#discard-ldap)
+5. [FAQ](#faq)
+
+**WARNING:** *the instructions given in this documentation are not meant
+to be used for production environments since it will make **Authelia**
+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 websites, it can be fine to use
+**Authelia** in a non highly-available manner. Fortunately, we can
+achieve to run it along with one reverse proxy meaning the setup is
+then reduced to only two components: Authelia 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
+it with a configuration file passed as argument.
+
+## Deploy with npm
+
+ npm install -g authelia
+ authelia /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
+
+## Deploy Nginx
+
+You also need to install nginx and take [example/nginx/minimal/nginx.conf](./example/nginx/minimal/nginx.conf) as an example of configuration.
+
+## Discard components
+
+### Discard MongoDB
+
+There is an option in the configuration file to discard MongoDB and use
+your local filesystem to store the database data. 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.
+
+Here is the configuration block you should use:
+
+ storage:
+ # The directory where the DB files will be saved
+ local:
+ path: /var/lib/authelia/store
+
+### Discard Redis
+
+There is an option in the configuration file to discard Redis and use the
+memory of the server to store the KV data. This option will therefore
+prevent you from running multiple instances of **Authelia** in parallel and
+will make you lose user sessions if the application restarts. This
+concretely means that all your users will need to authenticate again in
+that case. Hence, this option is not meant to be used in production.
+
+To use memory instead of a Redis backend, just comment out the Redis
+connection details in the following block:
+
+ session:
+ ...
+ # # The redis connection details
+ # redis:
+ # host: redis
+ # port: 6379
+ # password: authelia
+
+### Discard LDAP
+
+**Authelia** can use a file backend in order to store users instead of a
+LDAP server or an Active Directory. This mode will therefore prevent you
+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
+users you want.
+
+The content of this file is as follows:
+
+ users:
+ ...
+ john:
+ password: "{CRYPT}$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
+ email: john.doe@authelia.com
+ groups:
+ - admins
+ - dev
+
+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)))'
+
+Once the file is created, edit the configuration file with the following
+block (as used in [config.minimal.yml](../config.minimal.yml)):
+
+ authentication_backend:
+ file:
+ path: /etc/authelia/users_database.yml
+
+instead of (used in [config.template.yml](../config.template.yml)):
+
+ authentication_backend:
+ ldap:
+ url: ldap://openldap
+ base_dn: dc=example,dc=com
+
+ additional_users_dn: ou=users
+ users_filter: cn={0}
+
+ additional_groups_dn: ou=groups
+ groups_filter: (&(member={dn})(objectclass=groupOfNames))
+
+ group_name_attribute: cn
+
+ mail_attribute: mail
+
+ user: cn=admin,dc=example,dc=com
+ password: password
+
+## FAQ
+
+### Can you give more details on why this is not suitable for production environments?
+
+This documentation gives instructions that will make **Authelia** non
+highly-available and non scalable by preventing you from running multiple
+instances of the application.
+This means that **Authelia** won't be able to distribute the
+load accross multiple servers and it will prevent failover in case of a
+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?
+
+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.
+We would really be more than happy to review such a PR.
diff --git a/docs/deployment-production.md b/docs/deployment-production.md
new file mode 100644
index 00000000..835adb93
--- /dev/null
+++ b/docs/deployment-production.md
@@ -0,0 +1,58 @@
+# Deployment for Production
+
+**Authelia** can be deployed on bare metal or on Kubernetes with two
+different kind of artifacts: an npm package or a Docker image.
+
+**NOTE:** If not done already, we highly recommend you first follow the
+[Getting Started] documentation.
+
+## On Bare Metal
+
+**Authelia** has been designed to be a proxy companion handling the
+authentication and authorization requests for your entire infrastructure.
+
+As **Authelia** will be key in your architecture, it requires several
+components to make it highly-available. Deploying it in production means having an LDAP server for storing the information about the users, a Redis cache to store the user sessions in a distributed manner, a
+MongoDB to persist user configurations and one or more nginx reverse proxies configured to be used with Authelia. With such a setup **Authelia** can easily be scaled to multiple instances to evenly handle the traffic.
+
+**NOTE:** If you don't have all those components, don't worry, there is a way to deploy **Authelia** with only nginx. This is described in [Deployment for Devs].
+
+Here are the available steps to deploy **Authelia** given
+the configuration file is **/path/to/your/config.yml**. Note that you can
+create your own configuration file from [config.template.yml] located at
+the root of the repo.
+
+### Deploy With NPM
+
+ npm install -g authelia
+ authelia /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
+
+## On top of Kubernetes
+
+
+
+**Authelia** can also be used on top of [Kubernetes] using [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?
+
+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.
\ No newline at end of file
diff --git a/docs/deployment.md b/docs/deployment.md
deleted file mode 100644
index 53c077ad..00000000
--- a/docs/deployment.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Deployment
-
-**Authelia** can be deployed in two different ways: npm and docker.
-
-Here are the available steps to deploy **Authelia** on your machine given
-your configuration file is **/path/to/your/config.yml**. Note that you can
-create your own the configuration file from [config.template.yml] at the root
-of the repo.
-
-## Standalone
-
-**Authelia** has been designed to be a proxy companion handling the SSO.
-Therefore, deploying it in production means having an LDAP, a Redis, a
-MongoDB and one or more nginx running and configured to be used with
-Authelia.
-
-If you don't have all of this, don't worry, there is a way to deploy
-**Authelia** with only an nginx. To do so, please refer to the
-[Getting Started]. Otherwise here are the command to run Authelia in your
-environment.
-
-### With NPM
-
- npm install -g authelia
- authelia /path/to/your/config.yml
-
-### With Docker
-
- docker pull clems4ever/authelia
- docker run -v /path/to/your/config.yml:/etc/authelia/config.yml clems4ever/authelia
-
-## Kubernetes
-
-
-
-**Authelia** can also be used on top of Kubernetes using the nginx ingress
-controller.
-
-Please refer to the following [README](../example/kube/README.md) for more
-information.
-
-[config.template.yml]: ../config.template.yml
-[Getting Started]: ./getting-started.md
diff --git a/docs/features.md b/docs/features.md
index 98c4225a..98930922 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -11,7 +11,7 @@ You can find an example of the configuration of the LDAP backend in
[config.template.yml].
- 
+ 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 27163d65..758a3d15 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,17 +1,14 @@
# Getting Started
**Authelia** can be tested in a matter of seconds with docker-compose based
-on the latest image available on [Dockerhub] or by building the latest version
-from the sources and use it in docker-compose.
+on the latest image available on [Dockerhub].
## Pre-requisites
In order to test **Authelia**, we need to make sure that:
-- **Docker** and **docker-compose** are installed.
-- Some ports are open for listening on your machine.
-- Some subdomains redirect to your machine to simulate the fact that some
-applications you want to protect are served by some subdomains of
-**example.com** on your machine.
+- **Docker** and **docker-compose** are installed on your computer.
+- Ports 8080 and 8085 are not already used on your machine.
+- Some subdomains of **example.com** redirect to your test infrastructure.
### Docker & docker-compose
@@ -19,30 +16,27 @@ Make sure you have **docker** and **docker-compose** installed on your
machine.
Here are the versions used for testing in Travis:
- docker --version
+ $ docker --version
+ Docker version 17.03.1-ce, build c6d412e
-gave *Docker version 17.03.1-ce, build c6d412e*.
-
- docker-compose --version
-
-gave *docker-compose version 1.14.0, build c7bdf9e*.
+ $ docker-compose --version
+ docker-compose version 1.14.0, build c7bdf9e
### Available port
Make sure you don't have anything listening on port 8080 and 8085.
-The port 8080 will be used by nginx to serve **Authelia** and the applications
-we want to protect with **Authelia**.
+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 emails sent by **Authelia**
+The port 8085 is serving a webmail used to receive fake emails sent by **Authelia**
to validate your identity when registering U2F or TOTP secrets or when
resetting your password.
### Subdomain aliases
-Make sure the following subdomains redirect to your machine by adding the
-following lines to your **/etc/hosts**. It will alias the subdomains so that
-nginx can redirect requests to the correct virtual host.
+In order to simulate the behavior of a DNS resolving some test subdomains of **example.com** 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
127.0.0.1 public.example.com
@@ -53,40 +47,41 @@ nginx can redirect requests to the correct virtual host.
127.0.0.1 single_factor.example.com
127.0.0.1 login.example.com
-## From Dockerhub
+## Deploy
To deploy **Authelia** using the latest image from [Dockerhub], run the
following command:
./scripts/example-dockerhub/deploy-example.sh
-## From source
-
-To deploy **Authelia** from source, follow the [build] manual and run the
-following commands:
-
- ./scripts/example-commit/deploy-example.sh
-
## Test it!
After few seconds the services should be running and you should be able to
visit [https://home.example.com:8080/](https://home.example.com:8080/).
-When accessing the login page, a self-signed certificate exception should
-appear, it has to be trusted before you can get to the home page.
+When accessing the login page, since this is a test environment a
+self-signed certificate exception should appear, it has to be trusted
+before you can get to the home page.
The certificate must also be trusted for each subdomain, therefore it is
normal to see this exception several times.
-Below is what the login page looks like:
+Below is what the login page looks like after you accepted all exceptions:
-At some point, you'll be required to register a secret for setting up
-the second factor. **Authelia** will send an email to the user email
-address to confirm the user identity. In order to receive it, visit the
-webmail at [http://localhost:8085](http://localhost:8085).
+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 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
+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
+[http://localhost:8085](http://localhost:8085).
**Note:** If you cannot deploy the fake webmail for any reason. You can
configure **Authelia** to use the filesystem notifier (option available