[DOCS] Bootstrap new documentation website based on just-the-docs (#659)

.buildkite/deployment.yml

@@ -14,7 +14,7 @@ steps:
       DOCKER_CLI_EXPERIMENTAL: "enabled"
 
   - label: ":github: Deploy Artifacts"
-    command: ".buildkite/steps/ghartifacts.sh"
+    command: "ghartifacts.sh"
     retry:
       automatic: true
     agents:
@@ -24,4 +24,10 @@ steps:
 
   - label: ":linux: Deploy AUR"
     command: ".buildkite/steps/aurpackages.sh | buildkite-agent pipeline upload"
-    if: build.tag != null || build.branch == "master"
+    if: build.tag != null || build.branch == "master"
+
+  - label: ":docs: Deploy documentation"
+    command: "syncdoc.sh"
+    agents:
+      upload: "fast"
+    if: build.branch == "master"

.buildkite/steps/syncdoc.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -e
+
+rm -rf authelia
+git clone git@github.com:authelia/authelia.git --branch gh-pages
+
+pushd docs
+bundle install
+bundle exec jekyll build -d ../authelia
+popd
+
+COMMIT=$(git show -s --format=%h)
+
+pushd authelia
+git add -A
+git commit -m "synchronize docs of commit ${COMMIT}"
+git push
+popd
+
+rm -rf authelia

docs/.gitignore

@@ -0,0 +1,4 @@
+_site
+.sass-cache
+.jekyll-metadata
+.jekyll-cache

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

@@ -1,48 +0,0 @@
-# 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.
-
-<p align="center">
-  <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 (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
-      integration_key: ABCDEF
-      secret_key: 1234567890abcdefghifjkl
-
-This can be seen in [config.template.yml](../../config.template.yml) file.
-
-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="../../docs/images/duo-push-1.jpg" width="400">
-  <img src="../../docs/images/duo-push-2.png" width="400">
-</p>
-
-## Limitations
-
-Users must be enrolled via the Duo Admin panel, they cannot enroll a device from
-**Authelia** yet.
-
-
-## FAQ
-
-### 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,40 +0,0 @@
-# Security Keys (U2F)
-
-**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 to enrolled before authenticating.
-
-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.
-
-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="../../docs/images/REGISTER-U2F.png" width="400">
-</p>
-
-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?!
-
-## FAQ
-
-### Why don't I have access to the *Security Key* option?
-
-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

@@ -1,29 +0,0 @@
-# One-Time Passwords
-
-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="../../docs/images/2FA-TOTP.png" width="400">
-</p>
-
-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 **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="../../docs/images/REGISTER-TOTP.png" width="400">
-</p>
-
-You can use [Google Authenticator] to store it.
-
-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**.
-
-
-
-[Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en

docs/Gemfile

@@ -0,0 +1,30 @@
+source "https://rubygems.org"
+
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+# gem "jekyll", "~> 3.8.5"
+
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+#gem "minima", "~> 2.0"
+gem "just-the-docs"
+
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+gem "github-pages", group: :jekyll_plugins
+
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+  # gem "jekyll-feed", "~> 0.6"
+end
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.0" if Gem.win_platform?

docs/Gemfile.lock

@@ -0,0 +1,255 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.0.2.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    coffee-script (2.4.1)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.11.1)
+    colorator (1.1.0)
+    commonmarker (0.17.13)
+      ruby-enum (~> 0.5)
+    concurrent-ruby (1.1.6)
+    dnsruby (1.61.3)
+      addressable (~> 2.5)
+    em-websocket (0.5.1)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    ethon (0.12.0)
+      ffi (>= 1.3.0)
+    eventmachine (1.2.7)
+    execjs (2.7.0)
+    faraday (1.0.0)
+      multipart-post (>= 1.2, < 3)
+    ffi (1.12.2)
+    forwardable-extended (2.6.0)
+    gemoji (3.0.1)
+    github-pages (204)
+      github-pages-health-check (= 1.16.1)
+      jekyll (= 3.8.5)
+      jekyll-avatar (= 0.7.0)
+      jekyll-coffeescript (= 1.1.1)
+      jekyll-commonmark-ghpages (= 0.1.6)
+      jekyll-default-layout (= 0.1.4)
+      jekyll-feed (= 0.13.0)
+      jekyll-gist (= 1.5.0)
+      jekyll-github-metadata (= 2.13.0)
+      jekyll-mentions (= 1.5.1)
+      jekyll-optional-front-matter (= 0.3.2)
+      jekyll-paginate (= 1.1.0)
+      jekyll-readme-index (= 0.3.0)
+      jekyll-redirect-from (= 0.15.0)
+      jekyll-relative-links (= 0.6.1)
+      jekyll-remote-theme (= 0.4.1)
+      jekyll-sass-converter (= 1.5.2)
+      jekyll-seo-tag (= 2.6.1)
+      jekyll-sitemap (= 1.4.0)
+      jekyll-swiss (= 1.0.0)
+      jekyll-theme-architect (= 0.1.1)
+      jekyll-theme-cayman (= 0.1.1)
+      jekyll-theme-dinky (= 0.1.1)
+      jekyll-theme-hacker (= 0.1.1)
+      jekyll-theme-leap-day (= 0.1.1)
+      jekyll-theme-merlot (= 0.1.1)
+      jekyll-theme-midnight (= 0.1.1)
+      jekyll-theme-minimal (= 0.1.1)
+      jekyll-theme-modernist (= 0.1.1)
+      jekyll-theme-primer (= 0.5.4)
+      jekyll-theme-slate (= 0.1.1)
+      jekyll-theme-tactile (= 0.1.1)
+      jekyll-theme-time-machine (= 0.1.1)
+      jekyll-titles-from-headings (= 0.5.3)
+      jemoji (= 0.11.1)
+      kramdown (= 1.17.0)
+      liquid (= 4.0.3)
+      mercenary (~> 0.3)
+      minima (= 2.5.1)
+      nokogiri (>= 1.10.4, < 2.0)
+      rouge (= 3.13.0)
+      terminal-table (~> 1.4)
+    github-pages-health-check (1.16.1)
+      addressable (~> 2.3)
+      dnsruby (~> 1.60)
+      octokit (~> 4.0)
+      public_suffix (~> 3.0)
+      typhoeus (~> 1.3)
+    html-pipeline (2.12.3)
+      activesupport (>= 2)
+      nokogiri (>= 1.4)
+    http_parser.rb (0.6.0)
+    i18n (0.9.5)
+      concurrent-ruby (~> 1.0)
+    jekyll (3.8.5)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 0.7)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 1.14)
+      liquid (~> 4.0)
+      mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
+      rouge (>= 1.7, < 4)
+      safe_yaml (~> 1.0)
+    jekyll-avatar (0.7.0)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-coffeescript (1.1.1)
+      coffee-script (~> 2.2)
+      coffee-script-source (~> 1.11.1)
+    jekyll-commonmark (1.3.1)
+      commonmarker (~> 0.14)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-commonmark-ghpages (0.1.6)
+      commonmarker (~> 0.17.6)
+      jekyll-commonmark (~> 1.2)
+      rouge (>= 2.0, < 4.0)
+    jekyll-default-layout (0.1.4)
+      jekyll (~> 3.0)
+    jekyll-feed (0.13.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-gist (1.5.0)
+      octokit (~> 4.2)
+    jekyll-github-metadata (2.13.0)
+      jekyll (>= 3.4, < 5.0)
+      octokit (~> 4.0, != 4.4.0)
+    jekyll-mentions (1.5.1)
+      html-pipeline (~> 2.3)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-optional-front-matter (0.3.2)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-paginate (1.1.0)
+    jekyll-readme-index (0.3.0)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-redirect-from (0.15.0)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-relative-links (0.6.1)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-remote-theme (0.4.1)
+      addressable (~> 2.0)
+      jekyll (>= 3.5, < 5.0)
+      rubyzip (>= 1.3.0)
+    jekyll-sass-converter (1.5.2)
+      sass (~> 3.4)
+    jekyll-seo-tag (2.6.1)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-swiss (1.0.0)
+    jekyll-theme-architect (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-cayman (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-dinky (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-hacker (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-leap-day (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-merlot (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-midnight (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-minimal (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-modernist (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-primer (0.5.4)
+      jekyll (> 3.5, < 5.0)
+      jekyll-github-metadata (~> 2.9)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-slate (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-tactile (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-time-machine (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-titles-from-headings (0.5.3)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    jemoji (0.11.1)
+      gemoji (~> 3.0)
+      html-pipeline (~> 2.2)
+      jekyll (>= 3.0, < 5.0)
+    just-the-docs (0.2.7)
+      jekyll (~> 3.8.5)
+      jekyll-seo-tag (~> 2.0)
+      rake (~> 12.3.1)
+    kramdown (1.17.0)
+    liquid (4.0.3)
+    listen (3.2.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.3.6)
+    mini_portile2 (2.4.0)
+    minima (2.5.1)
+      jekyll (>= 3.5, < 5.0)
+      jekyll-feed (~> 0.9)
+      jekyll-seo-tag (~> 2.1)
+    minitest (5.14.0)
+    multipart-post (2.1.1)
+    nokogiri (1.10.8)
+      mini_portile2 (~> 2.4.0)
+    octokit (4.16.0)
+      faraday (>= 0.9)
+      sawyer (~> 0.8.0, >= 0.5.3)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (3.1.1)
+    rake (12.3.3)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rouge (3.13.0)
+    ruby-enum (0.7.2)
+      i18n
+    rubyzip (2.2.0)
+    safe_yaml (1.0.5)
+    sass (3.7.4)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    sawyer (0.8.2)
+      addressable (>= 2.3.5)
+      faraday (> 0.8, < 2.0)
+    terminal-table (1.8.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    thread_safe (0.3.6)
+    typhoeus (1.3.1)
+      ethon (>= 0.9.0)
+    tzinfo (1.2.6)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.6.1)
+    zeitwerk (2.2.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  github-pages
+  just-the-docs
+  tzinfo-data
+
+BUNDLED WITH
+   2.1.4

docs/_config.yml

@@ -0,0 +1,9 @@
+title: Authelia
+email: clement.michaud34@gmail.com
+description: Authelia is an open source multi-factor single sign-on portal for web applications
+baseurl: "/authelia"
+url: "https://authelia.github.io"
+logo: ./images/authelia-title.png
+footer_content: "Copyright &copy; 2020 Authelia. Distributed by an <a href=\"https://github.com/authelia/authelia/blob/master/LICENSE\">Apache 2.0 license.</a>"
+markdown: kramdown
+theme: just-the-docs

docs/_sass/overrides.scss

@@ -0,0 +1,10 @@
+
+img {
+    border: 1px solid #e6e6e6;
+    border-radius: 5px;
+    padding: 10px;
+}
+
+.no-border {
+    border: 0px;
+}

docs/configuration.md

@@ -1,33 +0,0 @@
-# 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.
-
-When running **Authelia**, you can specify your configuration file by passing
-the file path as the first argument of **Authelia**.
-
-    $ authelia --config config.custom.yml
-
-
-## Secrets
-
-Configuration of Authelia requires some secrets or passwords. Please
-note that the recommended way to set secrets in Authelia is to use
-environment variables.
-
-A secret in Authelia configuration could be set by providing the
-environment variable prefixed by AUTHELIA_ and with name equals to
-the capitalized path of the configuration key and with dots replaced
-by underscores.
-
-For instance the LDAP password is identified by the path
-**authentication_backend.ldap.password**, so this password could
-alternatively be set using the environment variable called
-**AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD**.
-
-If for some reason you prefer keeping the secrets in the configuration
-file, be sure to apply the right permissions to the file in order to
-prevent secret leaks if an another application gets compromised on your
-server. The UNIX permissions should probably be something like 600.

docs/configuration/access-control.md

@@ -0,0 +1,131 @@
+---
+layout: default
+title: Access Control
+parent: Configuration
+nav_order: 2
+---
+
+# Access Control
+{: .no_toc }
+
+## Access Control List
+
+With **Authelia** you can define a list of rules that are going to be evaluated in
+order when authorization is delegated to Authelia.
+
+The first matching rule of the list defines the policy applied to the resource and, if
+no rule matches the resource, a customizable default policy is applied.
+
+
+## Access Control Rule
+
+A rule defines two things:
+
+* the matching criterion of the request presented to the reverse proxy
+* the policy applied when all criterion match.
+
+The criterion are:
+
+* domain: domain targeted by the request.
+* resources: list of patterns that the path should match (one is sufficient).
+* subject: the user or group of users to define the policy for.
+* networks: the network range from where should comes the request.
+
+A rule is matched when all criterion of the rule match
+
+
+## Policies
+
+A policy represents the level of authentication the user needs to pass before
+being authorized to request the resource.
+
+There exist 4 policies:
+
+* bypass: the resource is public as the user does not need any authentication to
+get access to it.
+* one_factor: the user needs to pass at least the first factor to get access to
+the resource.
+* two_factor: the user needs to pass two factors to get access to the resource.
+* deny: the user does not have access to the resource.
+
+## Domains
+
+The domains defined in rules must obviously be either a subdomain of the domain
+protected by Authelia or the protected domain itself. In order to match multiple
+subdomains, the wildcard matcher character `*.` can be used as prefix of the domain.
+For instance, to define a rule for all subdomains of *example.com*, one would use
+`*.example.com` in the rule.
+
+## Resources
+
+A rule can define multiple regular expressions for matching the path of the resource. If
+any one of them matches, the resource criteria of the rule matches.
+
+
+## Subjects
+
+A subject is a representation of a user or a group of user for who the rule should apply.
+
+For a user with unique identifier `john`, the subject should be `user:john` and for a group
+uniquely identified by `developers`, the subject should be `group:developers`. Unlike resources
+there can be only one subject per rule. However, if multiple users or group must be matched by
+a rule, one can just duplicate the rule as many times as there are subjects.
+
+*Note: Any PR to make it a list instead of a single item is welcome.*
+
+## Networks
+
+A list of network ranges can be specified in a rule in order to apply different policies when
+requests come from different networks.
+
+The main use case is when, let say a resource should be exposed both on the Internet and from an
+authenticated VPN for instance. Passing a second factor a first time to get access to the VPN and
+a second time to get access to the application  can sometimes be cumbersome if the endpoint is not
+that much sensitive.
+
+Even if Authelia provides that flexbility, you might prefer higher level of security and avoid
+this option entirely. You and only you can define your security policy and it's up to you to
+configure Authelia accordingly.
+
+
+## Complete example
+
+Here is a complete example of complex access control list that can be defined in Authelia.
+
+    access_control:
+        default_policy: deny
+
+        rules:
+        - domain: public.example.com
+          policy: bypass
+
+        - domain: secure.example.com
+          policy: one_factor
+          networks:
+          - 192.168.1.0/24
+      
+        - domain: secure.example.com
+          policy: two_factor
+
+        - domain: singlefactor.example.com
+          policy: one_factor
+
+        - domain: "mx2.mail.example.com"
+          subject: "group:admins"
+          policy: deny
+        
+        - domain: "*.example.com"
+          subject: "group:admins"
+          policy: two_factor
+
+        - domain: dev.example.com
+          resources:
+          - "^/groups/dev/.*$"
+          subject: "group:dev"
+          policy: two_factor
+
+        - domain: dev.example.com
+          resources:
+          - "^/users/john/.*$"
+          subject: "user:john"
+          policy: two_factor

docs/configuration/authentication/file.md

@@ -0,0 +1,77 @@
+---
+layout: default
+title: File
+parent: Authentication backends
+grand_parent: Configuration
+nav_order: 1
+---
+
+# File
+
+**Authelia** supports a file as a users database.
+
+## Configuration
+
+Configuring Authelia to use a file is done by specifying the path to the
+file in the configuration file.
+
+    authentication_backend:
+        file:
+            path: /var/lib/authelia/users.yml
+
+
+## Format
+
+
+The format of the file is as follows.
+
+    users:
+        john:
+            password: "$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
+            email: john.doe@authelia.com
+            groups:
+                - admins
+                - dev
+
+        harry:
+            password: "$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
+            email: harry.potter@authelia.com
+            groups: []
+
+        bob:
+            password: "$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
+            email: bob.dylan@authelia.com
+            groups:
+                - dev
+
+        james:
+            password: "$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
+            email: james.dean@authelia.com
+
+This file should be set with read/write permissions as it could be updated by users
+resetting their passwords.
+
+## Passwords
+
+The file contains hash of passwords instead of plain text passwords for security reasons.
+
+You can use authelia binary or docker image to generate the hash of any password.
+
+For instance, with the docker image, just run
+
+    $ docker run authelia/authelia:latest authelia hash-password yourpassword
+    $6$rounds=50000$BpLnfgDsc2WD8F2q$be7OyobnQ8K09dyDiGjY.cULh4yDePMh6CUMpLwF4WHTJmLcPE2ijM2ZsqZL.hVAANojEfDu3sU9u9uD7AeBJ/
+
+
+## Password Hash Function
+
+The only supported hash function is salted sha512 determined by the prefix `$6$` as described
+in this [wiki](https://en.wikipedia.org/wiki/Crypt_(C)) page. 
+
+Although not the best hash function, Salted SHA512 is a decent algorithm given the number of rounds is big
+enough. It's not the best because the difficulty to crack the hash does not on the performance of the machine.
+The best algorithm, [Argon2](https://en.wikipedia.org/wiki/Argon2) does though. It won the
+[Password Hashing Competition](https://en.wikipedia.org/wiki/Password_Hashing_Competition) in 2015 and is now
+considered the best hashing function. There is an open [issue](https://github.com/authelia/authelia/issues/577)
+to add support for this hashing function.
+

docs/configuration/authentication/index.md

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Authentication backends
+parent: Configuration
+nav_order: 1
+has_children: true
+---
+
+# Authentication Backends
+
+There are two ways to store the users along with their password:
+
+* LDAP: users are stored in remote servers like OpenLDAP, OpenAM or Microsoft Active Directory.
+* File: users are stored in YAML file with a hashed version of their password.
+ 

docs/configuration/authentication/ldap.md

@@ -0,0 +1,62 @@
+---
+layout: default
+title: LDAP
+parent: Authentication backends
+grand_parent: Configuration
+nav_order: 2
+---
+
+# LDAP
+
+**Authelia** supports using a LDAP server as the users database.
+
+## Configuration
+
+Configuration of the LDAP backend is done as follows
+
+```yaml
+authentication_backend:
+    ldap:
+        # The url to the ldap server. Scheme can be ldap:// or ldaps://
+        url: ldap://127.0.0.1
+
+        # Skip verifying the server certificate (to allow self-signed certificate).
+        skip_verify: false
+
+        # The base dn for every entries
+        base_dn: dc=example,dc=com
+        
+        # An additional dn to define the scope to all users
+        additional_users_dn: ou=users
+        
+        # The users filter used to find the user DN
+        # {0} is a matcher replaced by username.
+        # 'cn={0}' by default.
+        users_filter: (cn={0})
+        
+        # An additional dn to define the scope of groups
+        additional_groups_dn: ou=groups
+        
+        # The groups filter used for retrieving groups of a given user.
+        # {0} is a matcher replaced by username.
+        # {dn} is a matcher replaced by user DN.
+        # {uid} is a matcher replaced by user uid.
+        # 'member={dn}' by default.
+        groups_filter: (&(member={dn})(objectclass=groupOfNames))
+        
+        # The attribute holding the name of the group
+        group_name_attribute: cn
+        
+        # The attribute holding the mail address of the user
+        mail_attribute: mail
+        
+        # The username and password of the admin user.
+        user: cn=admin,dc=example,dc=com
+        
+        # This secret can also be set using the env variables AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD
+        password: password
+```
+
+The user must have an email address in order for Authelia to perform
+identity verification when password reset request is initiated or
+when a second factor device is registered.

docs/configuration/duo-push-notifications.md

@@ -0,0 +1,27 @@
+---
+layout: default
+title: Duo Push Notifications
+parent: Configuration
+nav_order: 3
+---
+
+# Duo Push Notifications
+
+Authelia supports mobile push notifications relying on [Duo].
+
+Follow the instructions in the dedicated [documentation](../features/2fa/push-notifications.md)
+to know how to set up push notifications in Authelia.
+
+## Configuration
+
+The configuration is as follows:
+
+    duo_api:
+        hostname: api-123456789.example.com
+        integration_key: ABCDEF
+        secret_key: 1234567890abcdefghifjkl
+
+The secret key is shown as an example but you'd better set it using an environment
+variable as described [here](./secrets.md).
+
+[Duo]: https://duo.com/

docs/configuration/google-analytics.md

@@ -0,0 +1,13 @@
+---
+layout: default
+title: Google Analytics
+parent: Configuration
+nav_order: 4
+---
+
+# Google Analytics
+
+It is possible to provide a Google Analytics ID to Authelia in order
+to monitor the usage of the Sign-In portal.
+
+    google_analytics: UA-00000-01

docs/configuration/index.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: Configuration
+nav_order: 4
+has_children: true
+---
+
+# Configuration
+
+Authelia uses a YAML file as configuration file. A template with all possible
+options can be found [here](../config.template.yml), at the root of the repository.
+
+When running **Authelia**, you can specify your configuration by passing
+the file path as shown below.
+
+    $ authelia --config config.custom.yml

docs/configuration/miscellaneous.md

@@ -0,0 +1,53 @@
+---
+layout: default
+title: Miscellaneous
+parent: Configuration
+nav_order: 5
+---
+
+# Miscellaneous
+
+Here are the main customizable options in Authelia.
+
+## Host & Port
+`optional: true`
+
+Defines the address to listen on.
+
+    host: 0.0.0.0
+    port: 9091
+
+## Logs level
+
+`optional: true`
+
+Defines the level of logs used by Authelia. This level can be set to
+`trace`, `debug`, `info`.
+
+    logs_level: debug
+
+
+## JWT Secret
+
+`optional: false`
+
+Defines the secret used to craft JWT tokens leveraged by the identity
+verification process
+
+    jwt_secret: v3ry_important_s3cr3t
+
+## Default redirection URL
+
+`optional: true`
+
+The default redirection URL is the URL where users are redirected when Authelia
+cannot detect the target URL where the user was heading.
+
+In a normal authentication workflow, a user tries to access a website and she
+gets redirected to the sign-in portal in order to authenticate. Since the user
+initially targeted a website, the portal knows where the user was heading and
+can redirect her after the authentication process.
+However, when a user visits the sign in portal directly, the portal considers
+the targeted website is the portal. In that case and if the default redirection URL
+is configured, the user is redirected to that URL. If not defined, the user is not
+redirected after authentication.

docs/configuration/notifier/filesystem.md

@@ -0,0 +1,18 @@
+---
+layout: default
+title: Filesystem
+parent: Notifier
+grand_parent: Configuration
+nav_order: 1
+---
+
+# Filesystem
+
+With this configuration, the message will be sent to a file. This option
+should be used only for testing purpose.
+
+```yaml
+notifier:
+    filesystem:
+        filename: /tmp/authelia/notification.txt
+```

docs/configuration/notifier/index.md

@@ -0,0 +1,12 @@
+---
+layout: default
+title: Notifier
+parent: Configuration
+nav_order: 6
+has_children: true
+---
+
+# Notifier
+
+**Authelia** sometimes needs to send messages to users in order to
+verify their identity.

docs/configuration/notifier/smtp.md

@@ -0,0 +1,53 @@
+---
+layout: default
+title: SMTP
+parent: Notifier
+grand_parent: Configuration
+nav_order: 2
+---
+
+# SMTP
+
+**Authelia** can send emails to users through an SMTP server.
+It can be configured as described below.
+
+```yaml
+notifier:
+  # Use a SMTP server for sending notifications. Authelia uses PLAIN or LOGIN method to authenticate.
+  # [Security] By default Authelia will:
+  #   - force all SMTP connections over TLS including unauthenticated connections
+  #      - use the disable_require_tls boolean value to disable this requirement (only works for unauthenticated connections)
+  #   - validate the SMTP server x509 certificate during the TLS handshake against the hosts trusted certificates
+  #     - trusted_cert option:
+  #       - this is a string value, that may specify the path of a PEM format cert, it is completely optional
+  #       - if it is not set, a blank string, or an invalid path; will still trust the host machine/containers cert store
+  #     - defaults to the host machine (or docker container's) trusted certificate chain for validation
+  #     - use the trusted_cert string value to specify the path of a PEM format public cert to trust in addition to the hosts trusted certificates
+  #     - use the disable_verify_cert boolean value to disable the validation (prefer the trusted_cert option as it's more secure)
+  smtp:
+    username: test
+    # This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD
+    password: password
+    host: 127.0.0.1
+    port: 1025
+    sender: admin@example.com
+    ## disable_require_tls: false
+    ## disable_verify_cert: false
+    ## trusted_cert: ""
+```
+
+## Using Gmail
+
+You need to generate an app password in order to use Gmail SMTP servers. The process is
+described [here](https://support.google.com/accounts/answer/185833?hl=en)
+
+```yaml
+notifier:
+    smtp:
+        username: myaccount@gmail.com
+        # This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD
+        password: yourapppassword
+        sender: admin@example.com
+        host: smtp.gmail.com
+        port: 587
+```

docs/configuration/one-time-password.md

@@ -0,0 +1,17 @@
+---
+layout: default
+title: One-Time Password
+parent: Configuration
+nav_order: 6
+---
+
+# One-Time Password
+
+Applications generating one-time passwords usually displays an issuer to
+differentiate the various applications registered by the user.
+
+Authelia allows to customize the issuer to differentiate the entry created
+by Authelia from others.
+
+    totp:
+        issuer: authelia.com

docs/configuration/regulation.md

@@ -0,0 +1,27 @@
+---
+layout: default
+title: Regulation
+parent: Configuration
+nav_order: 7
+---
+
+# Regulation
+
+**Authelia** can temporarily ban accounts when there was too many
+authentication attempts. This helps prevent brute force attacks.
+
+## Configuration
+
+```yaml
+regulation:
+    # The number of failed login attempts before user is banned.
+    # Set it to 0 to disable regulation.
+    max_retries: 3
+
+    # The time range during which the user can attempt login before being banned.
+    # The user is banned if the authentication failed `max_retries` times in a `find_time` seconds window.
+    find_time: 120
+
+    # The length of time before a banned user can sign in again.
+    ban_time: 300
+```

docs/configuration/secrets.md

@@ -0,0 +1,44 @@
+---
+layout: default
+title: Secrets
+parent: Configuration
+nav_order: 8
+---
+
+# Secrets
+
+Configuration of Authelia requires some secrets and passwords.
+Even if they can be set in the configuration file, the recommended
+way to set secrets is to use environment variables as described
+below.
+
+## Environment variables
+
+A secret can be configured using an environment variable with name
+starting with AUTHELIA_ and followed by the path of the option capitalized
+and with dots replaced by underscores.
+
+For instance the LDAP password is identified by the path
+**authentication_backend.ldap.password**, so this password could
+alternatively be set using the environment variable called
+**AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD**.
+
+Here is the list of the environment variables which are considered
+secrets and can be defined. Any other option defined using an
+environment variable will not be replaced.
+
+* AUTHELIA_JWT_SECRET
+* AUTHELIA_DUO_API_SECRET_KEY
+* AUTHELIA_SESSION_SECRET
+* AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD
+* AUTHELIA_NOTIFIER_SMTP_PASSWORD
+* AUTHELIA_SESSION_REDIS_PASSWORD
+* AUTHELIA_STORAGE_MYSQL_PASSWORD
+* AUTHELIA_STORAGE_POSTGRES_PASSWORD
+
+## Secrets in configuration file
+
+If for some reason you prefer keeping the secrets in the configuration
+file, be sure to apply the right permissions to the file in order to
+prevent secret leaks if an another application gets compromised on your
+server. The UNIX permissions should probably be something like 600.

docs/configuration/session.md

@@ -0,0 +1,46 @@
+---
+layout: default
+title: Session
+parent: Configuration
+nav_order: 9
+---
+
+# Session
+
+**Authelia** relies on session cookies to authenticate users. When the user visits
+a website of the protected domain `example.com` for the first time, Authelia detects
+that there is no cookie for that user. Consequently, Authelia redirects the user
+to the login portal through which the user should authenticate to get a cookie which
+is valid for `*.example.com`, meaning all websites of the domain.
+At the next request, Authelia receives the cookie associated to the authenticated user
+and can then order the reverse proxy to let the request pass through to the application.
+
+## Configuration
+
+```yaml
+session:
+  # The name of the session cookie. (default: authelia_session).
+  name: authelia_session
+
+  # The secret to encrypt the session cookie.
+  # This secret can also be set using the env variables AUTHELIA_SESSION_SECRET
+  secret: unsecure_session_secret
+
+  # The time in seconds before the cookie expires and session is reset.
+  expiration: 3600 # 1 hour
+
+  # The inactivity time in seconds before the session is reset.
+  inactivity: 300 # 5 minutes
+
+  # The domain to protect.
+  # Note: the login portal must also be a subdomain of that domain.
+  domain: example.com
+
+  # The redis connection details (optional)
+  # If not provided, sessions will be stored in memory
+  redis:
+    host: 127.0.0.1
+    port: 6379
+    # This secret can also be set using the env variables AUTHELIA_SESSION_REDIS_PASSWORD
+    password: authelia
+```

docs/configuration/storage/index.md

@@ -0,0 +1,20 @@
+---
+layout: default
+title: Storage backends
+parent: Configuration
+nav_order: 10
+has_children: true
+---
+
+# Storage backends
+
+**Authelia** supports multiple storage backends. This backend is used
+to store user preferences, 2FA device handles and secrets, authentication
+logs, etc...
+
+The available options are:
+
+* [SQLite](./sqlite.html)
+* [MariaDB](./mariadb.html)
+* ~~MySQL~~ ([#512](https://github.com/authelia/authelia/issues/512))
+* [Postgres]((./postgres.html))

docs/configuration/storage/mariadb.md

@@ -0,0 +1,20 @@
+---
+layout: default
+title: MariaDB
+parent: Storage backends
+grand_parent: Configuration
+nav_order: 1
+---
+
+# MariaDB
+
+```yaml
+storage:
+    mysql:
+        host: 127.0.0.1
+        port: 3306
+        database: authelia
+        username: authelia
+        # This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
+        password: mypassword
+```

docs/configuration/storage/postgres.md

@@ -0,0 +1,20 @@
+---
+layout: default
+title: PostgreSQL
+parent: Storage backends
+grand_parent: Configuration
+nav_order: 2
+---
+
+# PostgreSQL
+
+```yaml
+storage:
+    postgres:
+        host: 127.0.0.1
+        port: 3306
+        database: authelia
+        username: authelia
+        # This secret can also be set using the env variables AUTHELIA_STORAGE_POSTGRES_PASSWORD
+        password: mypassword
+```

docs/configuration/storage/sqlite.md

@@ -0,0 +1,23 @@
+---
+layout: default
+title: SQLite
+parent: Storage backends
+grand_parent: Configuration
+nav_order: 3
+---
+
+# SQLite
+
+If you don't have a SQL server, you can use [SQLite](https://en.wikipedia.org/wiki/SQLite).
+However please note that this setup will prevent you from running multiple
+instances of Authelia since the database will be a local file.
+
+## Configuration
+
+Just give the path to the sqlite database. It will be created if the file does not exist.
+
+```yaml
+storage:
+    local:
+        path: /var/lib/authelia/db.sqlite3
+```

docs/contributing/authelia-scripts.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Authelia Scripts
+parent: Contributing
+---
+
 # Authelia Scripts
 
 Authelia comes with a set of dedicated scripts doing a broad range of operations such as

docs/contributing/build-and-dev.md

@@ -1,4 +1,11 @@
-# Build and dev
+---
+layout: default
+title: Build & Dev
+parent: Contributing
+nav_order: 1
+---
+
+# Build & Dev
 
 **Authelia** is written in Go and comes with a dedicated CLI called
 [authelia-scripts](./authelia-scripts.md) which is available after

docs/contributing/index.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Contributing
+nav_order: 7
+has_children: true
+---
+
+# Contributing

docs/contributing/suites.md

@@ -1,3 +1,10 @@
+---
+layout: default
+title: Suites
+parent: Contributing
+nav_order: 3
+---
+
 # Suites
 
 Authelia is a single component in interaction with many others in a complete

docs/deployment-dev.md

@@ -1,165 +0,0 @@
-# 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 SQL Server](#discard-sql-server)
-    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 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.
-
-As for a regular deployment in production, you need to install **Authelia**
-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/configuration.yml
-
-## Deploy with Docker
-
-    $ docker pull authelia/authelia
-    $ docker run -v /path/to/your/configuration.yml:/etc/authelia/configuration.yml authelia/authelia
-
-## 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 for your configuration.
-
-## Deploy Traefik
-
-TODO
-
-## Discard components
-
-### 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.
-
-Here is the configuration you should use:
-
-    storage:
-      # The file path of the sqlite3 file where data will be persisted
-      local:
-        path: /var/lib/authelia/db.sqlite3
-
-### 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 after
-a restart of Authelia. 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](../test/suites/basic/users_database.yml) and
-edit it to add the users you want.
-
-The content of this file is as follows:
-
-    users:
-      ...
-      john:
-        password: "$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
-(more hash algorithms such as Argon2 will be provided in the future).
-Here is a one-liner to generate such hashed password:
-
-    $ docker run authelia/authelia authelia hash-password yourpassword
-    $6$rounds=50000$BpLnfgDsc2WD8F2q$PumMwig8O0uIe9SgneL8Cm1FvUniOzpqBrH.uQE3aZR4K1dHsQldu5gEjJZsXcO./v3itfz6CXTDTJgeh5e8t.
-
-Copy this newly hashed password into your `users_database.yml` file.
-
-Once the file is created, edit the configuration file with the following
-block (as used in [configuration.yml](../test/suites/basic/configuration.yml)):
-
-    authentication_backend:
-      file:
-        path: /path/to/the/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 across 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 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
-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 *Standalone* [suite](./suites.md) to see all this
-in a real example.
-
-[Getting Started]: ./getting-started.md

docs/deployment/deployment-ha.md

@@ -1,4 +1,11 @@
-# Deployment for Production
+---
+layout: default
+title: Deployment - Highly-Available
+parent: Deployment
+nav_order: 2
+---
+
+# Highly-Available Deployment
 
 **Authelia** can be deployed on bare metal or on Kubernetes with two
 different kind of artifacts: the distributable version (binary and public_html)
@@ -42,16 +49,6 @@ pay attention to the permissions of the configuration file. See
 
     $ docker run -v /path/to/your/configuration.yml:/etc/authelia/configuration.yml -e TZ=Europe/Paris authelia/authelia
 
-## On top of Kubernetes
-
-<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).
-
-Please refer to the following [documentation](../internal/suites/example/kube/README.md)
-for more information.
-
 ## FAQ
 
 ### Why is this not automated?
@@ -59,9 +56,6 @@ for more information.
 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.
-
 
 
 [config.template.yml]: ../config.template.yml

docs/deployment/deployment-kubernetes.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Deployment - Kubernetes
+parent: Deployment
+nav_order: 3
+---
+
+# Deployment on Kubernetes
+
+<p>
+    <img src="../images/logos/kubernetes.logo.png" width="100" style="padding-right: 10px">
+</p>
+
+UNDER CONSTRUCTION

docs/deployment/deployment-lite.md

@@ -0,0 +1,61 @@
+---
+layout: default
+title: Deployment - Lite
+parent: Deployment
+---
+
+# Lite Deployment
+
+**Authelia** can be deployed as a lite setup not requiring any SQL server,
+Redis cluster or LDAP server. In some cases, like protecting personal projects/websites,
+it can be fine to use that setup but beware that this setup is non-resilient to failures
+so it should be used at your own risk.
+
+The setup is called lite since it reduces the number of components in the architecture to
+only two: a reverse proxy such as Nginx, Traefik or HAProxy and Authelia.
+
+## Reverse Proxy
+
+Documentation for deploying a reverse proxy collaborating with Authelia is available
+[here](./supported-proxies/index).
+
+## Discard components
+
+### Discard SQL server
+
+It's possible to use a SQLite file instead of a SQL server as documented
+[here](../configuration/storage/sqlite).
+
+### Discard Redis
+
+Connection details to Redis are optional. If not provided, sessions will
+be stored in memory instead. This has the inconvenient of logging out users
+every time Authelia restarts.
+
+The documentation about session management is available
+[here](../configuration/session).
+
+
+### Discard LDAP
+
+**Authelia** can use a file backend in order to store users instead of a
+LDAP server or an Active Directory.
+
+To use a file backend instead of a LDAP server, please follow the related
+documentation [here](../configuration/authentication/file).
+
+## FAQ
+
+### Can you give more details on why this is not suitable for production environments?
+
+This documentation gives instructions that will make **Authelia** non
+resilient to failures 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 across multiple servers and it will prevent failover in case of a
+crash or an hardware issue. Moreover, users will be logged out every time
+Authelia restarts.
+
+### Why aren't all those steps automated?
+
+We would really be more than happy to review any contribution with an Ansible playbook,
+a Chef cookbook or whatever else to automate the process.

docs/deployment/index.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Deployment
+nav_order: 5
+has_children: true
+---
+
+# Deployment

docs/deployment/supported-proxies/haproxy.md

@@ -0,0 +1,15 @@
+---
+layout: default
+title: HAProxy
+parent: Supported Proxies
+grand_parent: Deployment
+nav_order: 1
+---
+
+# HAProxy
+
+[HAProxy] is a reverse proxy supported by **Authelia**.
+
+UNDER CONSTRUCTION
+
+[HAproxy]: https://www.haproxy.org/

docs/deployment/supported-proxies/index.md

@@ -0,0 +1,12 @@
+---
+layout: default
+title: Supported Proxies
+parent: Deployment
+nav_order: 4
+has_children: true
+---
+
+# Supported Proxies
+
+**Authelia** works in collaboration with reverse proxies. Here you can find
+the documentation of the configuration required for every supported proxies.

docs/deployment/supported-proxies/nginx.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Nginx
+parent: Supported Proxies
+grand_parent: Deployment
+nav_order: 2
+---
+
 # Nginx
 
 [nginx] is a reverse proxy supported by **Authelia**.

docs/deployment/supported-proxies/traefik1.x.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Traefik 1.x
+parent: Supported Proxies
+grand_parent: Deployment
+nav_order: 3
+---
+
 # Traefik
 
 [Traefik 1.x] is a reverse proxy supported by **Authelia**.

docs/deployment/supported-proxies/traefik2.x.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Traefik 2.x
+parent: Supported Proxies
+grand_parent: Deployment
+nav_order: 3
+---
+
 # Traefik2
 
 [Traefik 2.x] is a reverse proxy supported by **Authelia**.

docs/features.md

@@ -1,77 +0,0 @@
-# Features in details
-
-## 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
-corresponds to the first factor. **Authelia** tries to bind the username and
-password against the configured LDAP backend.
-
-You can find an example of the configuration of the LDAP backend in
-[config.template.yml].
-
-<p align="center">
-  <img src="../docs/images/1FA.png" width="400">
-</p>
-
-
-## 2-Factor (2FA)
-
-**Authelia** comes with three kind of second factor.
-
-* Security keys like [Yubikey]. More info [here](./2factor/security-key.md).
-* One-Time Passwords generated by [Google Authenticator]. More info [here](./2factor/time-based-one-time-password.md).
-* 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="../docs/images/2FA-METHODS.png" width="400">
-</p>
-
-## Password reset
-
-With **Authelia**, you can also reset your password in no time. Click on the 
-**Forgot password?** link in the login page, provide the username of the user
-requiring a password reset and **Authelia** will send an email a confirmation
-email to the user email address.
-
-Proceed with the password reset form and validate to reset your password.
-
-<p align="center">
-  <img src="../docs/images/RESET-PASSWORD-STEP1.png" width="400">
-</p>
-
-## Access Control
-
-With **Authelia**, you can define your own access control rules for finely
-restricting user access to some resources and subdomains. Those rules are
-defined and fully documented in the configuration file. They can apply to
-users, groups or everyone.
-
-Check out [config.template.yml] to see how they are defined.
-
-## Single factor authentication
-
-**Authelia** allows you to customize the authentication method to use for each 
-subdomain. The supported methods are either "single_factor" or "two_factor". 
-Please check [config.template.yml] to see an example of configuration.
-
-It is also possible to use [basic authentication] to access a resource 
-protected by a single factor.
-
-Please note that Authelia uses the *Proxy-Authorization* header and not
-*Authorization* since one might be willing to authenticate against both
-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"
-
-## Session management with Redis
-
-When your users authenticate against Authelia, sessions are stored in a
-Redis key/value store. You can specify your own Redis instance in
-[config.template.yml].
-
-[basic authentication]: https://en.wikipedia.org/wiki/Basic_access_authentication
-[config.template.yml]: https://github.com/authelia/authelia/blob/master/config.template.yml
-[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
-[Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en

docs/features/2fa/index.md

@@ -0,0 +1,24 @@
+---
+layout: default
+title: Second Factor
+parent: Features
+nav_order: 1
+has_children: true
+---
+
+# Second Factor
+
+There are multiple supported options for the second factor.
+
+* Time-based One-Time passwords with [Google Authenticator]
+* Security Keys with tokens like [Yubikey].
+* Push notifications on your mobile using [Duo].
+
+<p align="center">
+  <img src="../../images/2FA-METHODS.png" width="400">
+</p>
+
+
+[Duo]: https://duo.com/
+[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
+[Google Authenticator]: https://google-authenticator.com/

docs/features/2fa/one-time-password.md

@@ -0,0 +1,38 @@
+---
+layout: default
+title: One-Time Password
+nav_order: 1
+parent: Second Factor
+grand_parent: Features
+---
+
+# Time-based One-Time Password
+
+**Authelia** supports Time-base one-time password generated by apps like [Google Authenticator].
+
+<p align="center">
+  <img src="../../images/2FA-TOTP.png" width="300">
+  <img src="../../images/google-authenticator.png" width="150" class="no-border" style="margin-left: 50px">
+</p>
+
+
+After having successfully completed the first factor, select **One-Time Password method**
+option and click on **Not registered yet?** link. This will send you an e-mail to confirm
+your identity.
+
+*NOTE: If you're testing **Authelia**, this e-mail has likely been sent to the mailbox available at https://mail.example.com:8080/*
+
+Once this validation step is completed, a QRCode gets displayed.
+
+<p align="center">
+  <img src="../../images/REGISTER-TOTP.png" width="400">
+</p>
+
+You can then use [Google Authenticator] to scan the code in order to register your device.
+
+From now on, you get tokens generated every 30 seconds that
+you can use to validate the second factor in **Authelia**.
+
+
+
+[Google Authenticator]: https://google-authenticator.com/

docs/features/2fa/push-notifications.md

@@ -0,0 +1,61 @@
+---
+layout: default
+title: Push Notification
+parent: Second Factor
+nav_order: 3
+grand_parent: Features
+---
+
+# Mobile Push Notification
+
+Mobile push notifications is the new trendy second factor method. When second factor is requested
+by Authelia, a notification is sent on your phone that you can either accept or deny.
+
+<p align="center">
+  <img src="../../images/duo-push-1.jpg" width="200">
+  <img src="../../images/duo-push-2.png" width="200">
+</p>
+
+
+Authelia leverages [Duo] third party to provide this feature.
+
+First, sign up on their website, log in, create a user account and attach it a mobile device.
+Beware that the name of the user must match the name of the user in Authelia.
+
+Then, in Duo interface, click on *Applications* and *Protect an Application*. Select the option
+*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 Authelia [configuration](../deployment/configuration.md) as shown below:
+
+    duo_api:
+      hostname: api-123456789.example.com
+      integration_key: ABCDEF
+      secret_key: 1234567890abcdefghifjkl
+
+Now that Authelia is configured, pass the first factor and select the Push notification
+option.
+
+<p align="center">
+  <img src="../../images/2FA-PUSH.png" width="400">
+</p>
+
+You should now receive a notification on your mobile phone with all the details
+about the authentication request.
+
+
+## Limitation
+
+Users must be enrolled via the Duo Admin panel, they cannot enroll a device from
+**Authelia** yet.
+
+
+## FAQ
+
+### 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).
+
+
+
+[Duo]: https://duo.com/

docs/features/2fa/security-key.md

@@ -0,0 +1,56 @@
+---
+layout: default
+title: Security Keys
+nav_order: 2
+parent: Second Factor
+grand_parent: Features
+---
+
+# Security Keys
+
+**Authelia** supports hardware-based second factors leveraging security keys like
+[Yubikeys](Yubikey).
+
+Security keys are among the most secure second factor. This method is already
+supported by many major applications and platforms like Google, Facebook, Github,
+some banks, and much more...
+
+<p align="center">
+  <img src="../../images/yubikey.jpg" width="150">
+</p>
+
+Normally, the protocol requires your security key to be enrolled on each site before
+being able to authenticate with it. Since Authelia provides Single Sign-On, your users
+will need to enroll their device only once to get access to all your applications.
+
+<p align="center">
+  <img src="../../images/REGISTER-U2F.png" width="400">
+</p>
+
+After having successfully passed the first factor, select *Security Key* method and
+click on *Not registered yet?* link. This will send you an email to verify your identity.
+
+*NOTE: This e-mail has likely been sent to the mailbox at https://mail.example.com:8080/ if you're testing Authelia.*
+
+Confirm your identity by clicking on **Register** and you'll be asked to
+touch the token of your security key to complete the enrollment.
+
+Upon successful enrollment, you can authenticate using your security key
+by simply touching the token again when requested:
+
+<p align="center">
+  <img src="../../images/2FA-U2F.png" width="400">
+</p>
+
+Easy, right?!
+
+## FAQ
+
+### Why don't I have access to the *Security Key* option?
+
+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/features/access-control.md

@@ -0,0 +1,29 @@
+---
+layout: default
+title: Access Control
+parent: Features
+nav_order: 5
+---
+
+# Access Control
+
+**Authelia** allows to define a fine-grained rule-based access control policy in
+configuration. This list of rules is tested against any requests protected by
+Authelia and defines the level of authentication the user must pass to get access
+to the resource.
+
+For instance a rule can look like this:
+
+    - domain: dev.example.com
+      resources:
+        - "^/groups/dev/.*$"
+      subject: "group:dev"
+      policy: two_factor
+
+This rule matches when the request targets the domain `dev.example.com` and the path
+matches the regular expression `^/groups/dev/.*$`. In that case, a two-factor policy
+is applied requiring the user to authenticate with two factors.
+
+## Configuration
+
+Please check the dedicated [documentation](./deployment/configuration/access-control.md)

docs/features/first-factor.md

@@ -0,0 +1,25 @@
+---
+layout: default
+title: First Factor
+parent: Features
+nav_order: 1
+---
+
+# First Factor
+
+2-Factor authentication is a method in which a user is granted access by presenting
+two pieces of evidence that she is who she claims to be.
+
+**Authelia** requires usual username and password as a first factor.
+
+<p align="center">
+  <img src="../images/1FA.png" width="400">
+</p>
+
+*IMPORTANT: This is the only method available as first factor.*
+
+Authelia supports several kind of users databases:
+
+* An LDAP server like OpenLDAP or OpenAM.
+* An Active Directory.
+* A YAML file

docs/features/index.md

@@ -0,0 +1,18 @@
+---
+layout: default
+title: Features
+nav_order: 3
+has_children: true
+---
+
+# Features
+
+**Authelia** is a 2FA & SSO authentication server which is dedicated
+to the security of applications and users. It can be considered
+as an extension of reverse proxies by providing features specific
+to authentication. You will find among other features:
+
+* Multiple two-factor methods.
+* Identity verification when registering second factor devices.
+* Reset password.
+* Ban account after too many attempts (known as regulation).

docs/features/password-reset.md

@@ -0,0 +1,31 @@
+---
+layout: default
+title: Password Reset
+parent: Features
+nav_order: 4
+---
+
+# Password Reset
+
+**Authelia** provides workflow to let users reset their password when they lose it.
+
+A simple click on `Forgot password?` for starting the process. Note that resetting a
+password requires a new identity verification using the e-mail of the user.
+
+<p align="center">
+  <img src="../images/1FA.png" width="400">
+</p>
+
+Give your username and receive an e-mail to verify your identity.
+
+<p align="center">
+  <img src="../images/RESET-PASSWORD-STEP1.png" width="400">
+</p>
+
+Once your identity is verified, fill in the form to reset your password.
+
+<p align="center">
+  <img src="../images/RESET-PASSWORD-STEP2.png" width="400">
+</p>
+
+Now you can authenticate with your new credentials.

docs/features/regulation.md

@@ -0,0 +1,17 @@
+---
+layout: default
+title: Regulation
+parent: Features
+nav_order: 6
+---
+
+# Regulation
+
+**Authelia** takes the security of users very seriously and comes with
+a way to avoid brute forcing the first factor by regulating the
+authentication attempts and temporarily ban an account when too many
+attempts have been made.
+
+## Configuration
+
+Please check the dedicated [documentation](./deployement/configuration/regulation.md).

docs/features/single-factor.md

@@ -0,0 +1,29 @@
+---
+layout: default
+title: Single Factor
+parent: Features
+nav_order: 3
+---
+
+# Single Factor
+
+**Authelia** supports single factor authentication to let applications
+send authenticated requests to other applications.
+
+Single or two-factor authentication can be configured per resource of an
+application for flexibility.
+
+For instance, you can configure Authelia to grant access to all resources
+matching `app1.example.com/api/(.*)` with only a single factor and all
+resources matching `app1.example.com/admin` with two factors.
+
+To know more about the configuration of the feature, please visit the
+documentation about the [configuration](../deployment/configuration.md).
+
+
+## Proxy-Authorization header
+
+Authelia reads credentials from the header `Proxy-Authorization` instead of
+the usual `Authorization` header. This is because in some circumstances both Authelia
+and the application could require authentication in order to provide specific
+authorizations at the level of the application.

docs/getting-started.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+---
+
 # Getting Started
 
 **Authelia** can be tested in a matter of seconds with Docker and docker-compose.
@@ -59,15 +65,25 @@ Here are the versions used for testing in Buildkite:
     $ docker-compose --version
     docker-compose version 1.24.1, build unknown
 
-### How am I supposed to access the subdomains of example.com?
+### How can I serve my application under example.com?
 
-In order to test Authelia, Authelia fakes your browser by adding entries
+Don't worry, you don't need to own the domain *example.com* to test Authelia.
-in /etc/hosts when you first source the bootstrap.sh script.
+Copy the following lines in your /etc/hosts.
+
+    192.168.240.100 home.example.com
+    192.168.240.100 login.example.com
+    192.168.240.100 singlefactor.example.com
+    192.168.240.100 public.example.com
+    192.168.240.100 secure.example.com
+    192.168.240.100 mail.example.com
+    192.168.240.100 mx1.mail.example.com
+
+`192.168.240.100` is the IP attributed by Docker to the reverse proxy. Once done
+you can access the listed sub-domains from your browser and they will target
+the reverse proxy.
 
 ### What should I do if I want to contribute?
 
-You can refer to the dedicated documentation [here](./build-and-dev.md).
+You can refer to the dedicated documentation [here](./contributing/index.md).
 
-[config.template.yml]: ../config.template.yml
+[suite]: ./contributing/suites.md
-[DockerHub]: https://hub.docker.com/r/authelia/authelia/
-[suite]: ./suites.md

docs/home/architecture.md

@@ -0,0 +1,48 @@
+---
+layout: default
+title: Architecture
+parent: Home
+nav_order: 1
+---
+
+# Architecture
+
+**Authelia** is a companion of reverse proxies like Nginx, Traefik and HAProxy.
+It can be seen as an extension of those proxies providing authentication functions
+and a login portal.
+
+As shown in the following architecture diagram, Authelia is directly connected to
+the reverse proxy but never directly connected to application backends.
+
+<p align="center" style="margin:50px">
+  <img src="../images/archi.png"/>
+</p>
+
+## Workflow
+
+Reverse proxies are configured so that every incoming requests generates an authentication
+request sent to Authelia and to which Authelia responds to order the reverse
+proxy to let the incoming request pass through or block it because user is not authenticated
+or is not sufficiently authorized.
+
+### Step by step
+
+When the first request of an unauthenticated user hits the reverse proxy, Authelia
+determines the user is not authenticated because no session cookie has been sent along with
+the request. Consequently, Authelia redirects the user to the authentication portal provided
+by Authelia itself. The user can then execute the authentication workflow using that portal
+to obtain a session cookie valid for all subdomains of the domain protected by Authelia.
+
+When the user visits the initial website again, the query is sent along with the
+session cookie which is forwarded in the authentication request to Authelia. This time,
+Authelia can verify the user is authenticated and order the reverse proxy to let the query
+pass through.
+
+### Sequence Diagram
+
+Here is a description of the complete workflow:
+
+<p align="center">
+  <img src="../images/sequence-diagram.png"/>
+</p>
+

docs/index.md

@@ -0,0 +1,63 @@
+---
+layout: default
+title: Home
+nav_order: 1
+has_children: true
+---
+
+# Home
+
+*It has never been so easy to secure your applications with Single Sign-On
+and Two-Factor.*
+
+
+With **Authelia** you can login once and get access to all your web apps
+safely from the Web thanks to two-factor authentication.
+
+<p align="center">
+  <img src="./images/1FA.png" width="400" />
+</p>
+
+**Authelia** is an open source authentication and authorization server
+protecting modern web applications by collaborating with reverse proxies
+such as NGINX, Traefik and HAProxy. Consequently, no code is required to
+protect your apps.
+
+<p align="center" style="margin:50px">
+  <img src="./images/archi.png"/>
+</p>
+
+Multiple 2-factor methods are available for satisfying every users.
+
+* Time-based One-Time passwords with [Google Authenticator].
+* Security Keys with tokens like [Yubikey].
+* Push notifications on your mobile using [Duo].
+
+**Authelia** is available as Docker images, static binaries and AUR packages
+so that you can test it in minutes. Let's begin with the
+[Getting Started](./getting-started).
+
+
+## Authelia...
+
+* is not an OAuth or OpenID Connect provider yet.
+* is not a SAML provider yet.
+<<<<<<< HEAD
+* does not support support authentication against an OAuth or OpenID Connect provider.
+* does not support using hardware devices as single factor.
+* does not allow provide a PAM module yet.
+=======
+* does not support authentication against an OAuth or OpenID Connect provider.
+* does not support authentication against a SAML provider.
+* does not support using hardware devices as single factor.
+* does not provide a PAM module yet.
+>>>>>>> [WIP] Use 'Just-the-docs' jekyll theme to organize documentation.
+
+
+[Duo]: https://duo.com/
+[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
+<<<<<<< HEAD
+[Google Authenticator]: https://google-authenticator.com/
+=======
+[Google Authenticator]: https://google-authenticator.com/
+>>>>>>> [WIP] Use 'Just-the-docs' jekyll theme to organize documentation.

docs/security/index.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Security
+nav_order: 6
+has_children: true
+---
+
+# Security

docs/security/measures.md

@@ -1,4 +1,11 @@
-# Security
+---
+layout: default
+title: Security Measures
+parent: Security
+nav_order: 2
+---
+
+# Security Measures
 
 ## Protection against cookie theft
 
@@ -93,10 +100,4 @@ add_header X-Frame-Options "SAMEORIGIN";
 add_header X-XSS-Protection "1; mode=block";
 ```
 
-## Contributing
-
-If you find possible vulnerabilities or threats, do not hesitate to contribute
-either by writing a test case demonstrating the possible attack and if
-possible some solutions to prevent it or submit a PR.
-
 [HSTS]: https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/

docs/security/report.md

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Report Vulnerabilities
+parent: Security
+nav_order: 1
+---
+
+# Report Vulnerabilities
+
+Security is taken very seriously here, therefore we follow the rule of
+responsible disclosure and we encourage you to do so.
+
+Would you like to report any vulnerability discovered in Authelia, please
+first contact **clems4ever** on [Matrix](https://riot.im/app/#/room/#authelia:matrix.org)
+or by [email](mailto:clement.michaud34@gmail.com).

go.sum

@@ -126,6 +126,7 @@ github.com/konsorten/go-windows-terminal-sequences v1.0.1 h1:mweAR1A6xJ3oS2pRaGi
 github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
 github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515/go.mod h1:+0opPa2QZZtGFBFZlji/RkVcI2GknAs/DXo4wKdlNEc=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pty v1.1.1 h1:VkoXIwSboBpnk99O/KFauAEILuNHv5DVFKZMBN/gUgw=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/pty v1.1.8 h1:AkaSdXYQOWeaO3neb8EM634ahkXXe3jYbVh/F9lq+GI=
 github.com/kr/pty v1.1.8/go.mod h1:O1sed60cT9XZ5uDucP5qwvh+TE3NnUj51EiZO/lmSfw=