Merge pull request #302 from clems4ever/improve-doc

Add details on how to deploy Authelia in a dev environment.

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
 

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
+tests for **Authelia**: unit tests for the server, the client and a shared
-and integration tests for both.
+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
 

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

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.

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
+
+<img src="/images/kube-logo.png" width="24" align="left">
+
+**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.

docs/deployment.md

@@ -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
-
-<img src="/images/kube-logo.png" width="24" align="left">
-
-**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

docs/features.md

@@ -11,7 +11,7 @@ You can find an example of the configuration of the LDAP backend in
 [config.template.yml].
 
 <p align="center">
-  <img src="../images/second_factor.png" width="400">
+  <img src="../images/first_factor.png" width="400">
 </p>
 
 

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
+on the latest image available on [Dockerhub].
-from the sources and use it in docker-compose.
 
 ## Pre-requisites
 
 In order to test **Authelia**, we need to make sure that:
-- **Docker** and **docker-compose** are installed.
+- **Docker** and **docker-compose** are installed on your computer.
-- Some ports are open for listening on your machine.
+- Ports 8080 and 8085 are not already used on your machine.
-- Some subdomains redirect to your machine to simulate the fact that some
+- Some subdomains of **example.com** redirect to your test infrastructure.
-applications you want to protect are served by some subdomains of
-**example.com** on your machine.
 
 ### 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
-
+    docker-compose version 1.14.0, build c7bdf9e
-    docker-compose --version
-
-gave *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
+The port 8080 will be our frontend load balancer serving both **Authelia**'s portal and the applications we want to protect.
-we want to protect with **Authelia**.
 
-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
+In order to simulate the behavior of a DNS resolving some test subdomains of **example.com** to your machine, we
-following lines to your **/etc/hosts**. It will alias the subdomains so that
+need to add the following lines to your **/etc/hosts**. It will alias the
-nginx can redirect requests to the correct virtual host.
+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
+When accessing the login page, since this is a test environment a
-appear, it has to be trusted before you can get to the home page.
+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:
 
 <p align="center">
   <img src="../images/first_factor.png" width="400">
 </p>
 
-At some point, you'll be required to register a secret for setting up
+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
-the second factor. **Authelia** will send an email to the user email
+group is also provided there.
-address to confirm the user identity. In order to receive it, visit the
+
-webmail at [http://localhost:8085](http://localhost:8085).
+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