diff --git a/README.md b/README.md
index 4105c61..4382d6f 100644
--- a/README.md
+++ b/README.md
@@ -2,218 +2,155 @@ mxisd - Federated Matrix Identity Server Daemon
 -----
 ![Travis-CI build status](https://travis-ci.org/kamax-io/mxisd.svg?branch=master)  
 
-[Overview](#overview) | [Features](#features) | [Lookup process](#lookup-process) | [Packages](#packages) | 
-[From source](#from-source) | [Configuration](#configuration) | [Network Discovery](#network-discovery) | 
-[Integration](#integration) | [Support](#support)
+- [Overview](#overview)
+- [Features](#features)
+- [Why use mxisd](#why-use-mxisd)
+- [Quick start](#quick-start)
+- [Support](#support)
+- [Contribute](#contribute) 
+- [FAQ](#faq)
+- [Contact](#contact)
 
 # Overview
-mxisd is a Federated Matrix Identity server for self-hosted Matrix infrastructures.
+mxisd is a Federated Matrix Identity server for self-hosted Matrix infrastructures with enhanced features.
+  
+It is specifically designed to connect to an Identity store (AD/Samba/LDAP, SQL Database, Web services/application, ...)
+to ease integration of the Matrix ecosystem with an existing infrastructure, or to build a new one using lasting tools.
 
-mxisd uses a cascading lookup model which performs lookup from a more authoritative to a less authoritative source, usually doing:
-- Local identity stores: LDAP, etc.
-- Federated identity stores: another Identity Server in charge of a specific domain, if applicable
-- Configured identity stores: another Identity Server specifically configured, if part of some sort of group trust
-- Root identity store: vector.im/matrix.org central Identity Servers
+mxisd core principle is to map between Matrix IDs and 3PIDs (Thrid-party Identifiers) for the Homeserver and its users.
+3PIDs can be anything that identify a user, like:
+- Email address
+- Phone number
+- Skype/Live ID
+- Twitter handle
+- Facebook ID
+- ...
 
-mxisd provides an alternative to [sydent](https://github.com/matrix-org/sydent), while still connecting to the vector.im and matrix.org Identity servers, 
-by implementing the [Matrix Identity Service specification](https://matrix.org/docs/spec/identity_service/unstable.html).
-
-mxisd only aims to support workflows that do NOT break federation or basic lookup processes of the Matrix ecosystem.
+mxisd is an enhanced Identity service, which implements the [Matrix Identity service API](https://matrix.org/docs/spec/identity_service/unstable.html)
+but also several other features that greatly enhance user experience within Matrix.
 
 # Features
-- Single lookup of 3PID (E-mail, phone number, etc.) by the Matrix Client or Homeserver.
-- Bulk lookups when trying to find possible matches within contacts in Android and iOS clients.
-- Bind of 3PID by a Matrix user within a Matrix client - See [documentation](docs/sessions/3pid.md)
-- Support of invitation to rooms by e-mail with e-mail notification to invitee.
-- Authentication support in [synapse](https://github.com/matrix-org/synapse) via the [REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth).
+As a [regular Matrix Identity service](docs/features/identity.md):
+- Search for people by 3PID using its own Identity stores (LDAP, SQL, etc.)
+- Invite people to rooms by 3PID using its own Identity stores, with [notifications](docs/README.md)
+to the invitee (Email, SMS, etc.)
+- Allow users to add 3PIDs to their settings/profile
 
-In the pipe:
-- Support to proxy 3PID bindings in user profile to the central Matrix.org servers
+As an enhanced Identity service:
+- Use a recursive lookup mechanism when searching and inviting people by 3PID, allowing to fetch data from:
+  - Own Identity store
+  - Federated Identity servers, if applicable to the 3PID
+  - Arbitrary Identity servers
+  - Central Matrix Identity servers
+- [Extensive control of where 3PIDs are transmited](docs/sessions/3pid.md), so they are not leaked publicly by users 
+- [Authentication support](docs/features/authentication.md) for [synapse](https://github.com/matrix-org/synapse) via the
+[REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth).
+- [Directory integration](docs/features/directory-users.md) which allows you to search for users within your
+organisation, even without prior Matrix contact.
+- [Auto-fill of user profile](docs/features/authentication.md) (Display name, 3PIDs) via the
+[REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth)
 
-# Lookup Process
-Default Lookup strategy will use a priority order and a configurable recursive/local type of request.
+# Why use mxisd
+- Use your existing Identity store, do not duplicate information
+- Auto-fill user profiles with relevant info
+- As an organisation, stay in control of 3PIDs so they are not published to the central Matrix.org servers where they
+currently **cannot be removed**
+- Users can directly find each other using whatever attribute is relevant within your Identity store
+- Federate your Identity lookups so you can discover others and/or others can discover you, all with extensive ACLs
 
-## E-mail
-Given the 3PID `john.doe@example.org`, the following will be performed until a mapping is found:
-- LDAP: lookup the Matrix ID (partial or complete) from a configurable attribute using a dedicated query.
-- DNS: lookup another Identity Server using the domain part of an e-mail and:
-  - Look for a SRV record under `_matrix-identity._tcp.example.org`
-  - Lookup using the base domain name `example.org`
-- Forwarder: Proxy the request to other configurable identity servers.
+# Quick Start
+1. [Preparation](#preparation)
+2. [Install](#install)
+3. [Configure](#configure)
+4. [Integrate](#integrate)
+5. [Validate](#validate)
 
-## Phone number
-Given the phone number `+123456789`, the following lookup logic will be performed:
-- LDAP: lookup the Matrix ID (partial or complete) from a configurable attribute using a dedicated query.
-- Forwarder: Proxy the request to other configurable identity servers.
+Following these quick start instructions, you will have a basic setup that can perform recursive/federated lookups and
+talk to the central Matrix.org Identity service.  
+This will be a good ground work for further integration with your existing Identity stores.
 
-# Packages
-See [releases]((https://github.com/kamax-io/mxisd/releases)) for native installers of supported systems.  
-If none is available, please use other packages or build from source.
+## Preparation
+You will need:
+- Homeserver
+- Reverse proxy with regular TLS/SSL certificate (Let's encrypt) for your mxisd domain
 
-## Debian
-### Download
-See the [releases section](https://github.com/kamax-io/mxisd/releases).
+As synapse requires an HTTPS connection when talking to an Identity service, a reverse proxy is required as mxisd does
+not support HTTPS listener at this time.
 
-### Configure and run
-After installation:
-1. Copy the sample config file `/etc/mxisd/mxisd-sample.yaml` to `/etc/mxisd/mxisd.yaml`
-2. [Configure](#configuration)
-3. Start the service: `sudo systemctl start mxisd`
+For maximum integration, it is best to have your Homeserver and mxisd reachable via the same hostname.  
+You can also use a dedicated domain for mxisd, but will not have access to some features.
 
-### From source
-Requirements:
-- fakeroot
-- dpkg-deb
+Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-io/mxisd/wiki/Gotchas#nating) if you use the same
+hostname.
 
-Run:
-```
-./gradlew buildDeb 
-```
-You will find the debian package in `build/dist`
-
-## Docker
-```
-docker pull kamax/mxisd
-```
-
-For more info, see [the public repository](https://hub.docker.com/r/kamax/mxisd/)
-### From source
-[Build mxisd](#build) then build the docker image:
-```
-./gradlew dockerBuild
-```
-You can run a container of the given image and test it with the following command (adapt volumes host paths):
-```
-docker run -v /data/mxisd/etc:/etc/mxisd -v /data/mxisd/var:/var/mxisd -p 8090:8090 -t kamax/mxisd:latest-dev
-```
-
-# From Source
-## Requirements
-- JDK 1.8
-
-## Build
-```
-git clone https://github.com/kamax-io/mxisd.git
-cd mxisd
-./gradlew build
-```
-then see the [Configuration](#configuration) section.
-
-## Test build
-Start the server in foreground to validate the build:
-```
-java -jar build/libs/mxisd.jar
-```
-
-Ensure the signing key is available:
-```
-$ curl http://localhost:8090/_matrix/identity/api/v1/pubkey/ed25519:0
-{"public_key":"..."}
-```
-
-Test basic recursive lookup (requires Internet connection with access to TCP 443):
-```
-$ curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=mxisd-lookup-test@kamax.io'
-{"address":"mxisd-lookup-test@kamax.io","medium":"email","mxid":"@mxisd-lookup-test:kamax.io",...}
-```
-
-
-If you enabled LDAP, you can also validate your config with a similar request after replacing the `address` value with something present within your LDAP
-```
-curl "http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=john.doe@example.org"
-```
-
-If you plan on testing the integration with a homeserver, you will need to run an HTTPS reverse proxy in front of it
-as the reference Home Server implementation [synapse](https://github.com/matrix-org/synapse) requires a HTTPS connection
-to an ID server.  
-See the [Integration section](#integration) for more details.
+The following Quick Start guide assumes you will host the Homeserver and mxisd under the same hostname.
 
 ## Install
-After [building](#build) the software, run all the following commands as `root` or using `sudo`
-1. Prepare files and directories:
+Install via:
+- [Debian package](docs/install/debian.md)
+- [Docker image](docs/install/docker.md)
+- [Sources](docs/build.md)
+
+See the [Latest release](https://github.com/kamax-io/mxisd/releases/latest) for links to each.
+
+## Configure
+Create/edit a minimal configuration (see installer doc for the location):
 ```
-# Create a dedicated user
-useradd -r mxisd
+matrix.domain: 'MyMatrixDomain.org'
+key.path: '/path/to/signing.key.file'
+storage.provider.sqlite.database: '/path/to/mxisd.db'
+```  
+- `matrix.domain` should be set to your Homeserver domain
+- `key.path` will store the signing keys, which must be kept safe!
+- `storage.provider.sqlite.database` is the location of the SQLite Database file which will hold state (invites, etc.)
 
-# Create bin directory
-mkdir /opt/mxisd
+If your HS/mxisd hostname is not the same as your Matrix domain, configure `server.name`.  
+Complete configuration guide is available [here](docs/configure.md).
 
-# Create config directory and set ownership
-mkdir /etc/mxisd
-chown mxisd /etc/mxisd
-
-# Create data directory and set ownership
-mkdir /var/opt/mxisd
-chown mxisd /var/opt/mxisd
-
-# Copy <repo root>/build/libs/mxisd.jar to bin directory
-cp ./build/libs/mxisd.jar /opt/mxisd/
-chown mxisd /opt/mxisd/mxisd.jar
-chmod a+x /opt/mxisd/mxisd.jar
-
-# Create symlink for easy exec
-ln -s /opt/mxisd/mxisd.jar /usr/bin/mxisd
+## Integrate
+### Reverse proxy
+#### Apache2
+In the VirtualHost handling the domain with SSL, add the following line, replacing `0.0.0.0` by the right address/host.  
+**This line MUST be present before the one for the homeserver!**
+```
+ProxyPass /_matrix/identity http://0.0.0.0:8090/_matrix/identity
 ```
 
-2. Copy the config file created earlier `./application.example.yaml` to `/etc/mxisd/mxisd.yaml`
-3. [Configure](#configuration)
-4. Copy `<repo root>/src/systemd/mxisd.service` to `/etc/systemd/system/` and edit if needed
-5. Enable service for auto-startup
+Typical VirtualHost configuration would be:
 ```
-systemctl enable mxisd
-```
-6. Start mxisd
-```
-systemctl start mxisd
+<VirtualHost *:443>
+    ServerName example.org
+    
+    ...
+    
+    ProxyPreserveHost on
+    ProxyPass /_matrix/identity/ http://10.1.2.3:8090/_matrix/identity/
+    ProxyPass /_matrix/ http://10.1.2.3:8008/_matrix/
+</VirtualHost>
 ```
 
-# Configuration
-After following the specific instructions to create a config file from the sample:
-1. Set the `matrix.domain` value to the domain value used in your Home Server configuration
-2. Set an absolute location for the signing keys using `key.path`
-3. Configure the E-mail notification sender following [the documentation](docs/threepids/medium/email/smtp-connector.md)
-4. If you would like to support Phone number validation, see the [Twilio configuration](docs/threepids/medium/msisdn/twilio-connector.md)
-
-In case your IS public domain does not match your Matrix domain, see `server.name` and `server.publicUrl` 
-config items.
-
-
-## Backends
-### LDAP (AD, Samba, LDAP)
-If you want to use LDAP backend as an Identity store:
-1. Enable it with `ldap.enabled`
-2. Configure connection options using items starting in `ldap.connection`
-3. You may want to valid default values for `ldap.attribute` items
-
-### SQL (SQLite, PostgreSQL)
-If you want to connect to use a synapse DB (SQLite or PostgreSQL) as Identity store, follow the example config for `sql` config items.
-
-### REST (Webapps/websites integration)
-If you want to use the REST backend as an Identity store:
-1. Enable it with `rest.enabled`
-2. Configure options starting with `rest` and see the dedicated documentation in `docs/backends/rest.md`
-
-# Network Discovery
-To allow other federated Identity Server to reach yours, the same algorithm used for Homeservers takes place:
-1. Check for the appropriate DNS SRV record
-2. If not found, use the base domain
- 
-If your Identity Server public hostname does not match your Matrix domain, configure the following DNS SRV entry 
-and replace `matrix.example.com` by your Identity server public hostname - **Make sure to end with a final dot!**
+### Synapse
+Add your mxisd domain into the `homeserver.yaml` at `trusted_third_party_id_servers` and restart synapse.  
+In a typical configuration, you would end up with something similair to:
 ```
-_matrix-identity._tcp.example.com. 3600 IN SRV 10 0 443 matrix.example.com.
-``` 
-This would only apply for 3PID that are DNS-based, like e-mails. For anything else, like phone numbers, no federation 
-is currently possible.  
+trusted_third_party_id_servers:
+    - matrix.org
+    - vector.im
+    - example.org
+```
+It is recommended to remove `matrix.org` and `vector.im` so only your own Identity server is allowed by synapse. 
 
-The port must be HTTPS capable. Typically, the port `8090` of mxisd should be behind a reverse proxy which does HTTPS.
-See the [integration section](#integration) for more details.
+### Federation and network discovery
+See the [dedicated document](docs/features/federation.md).
 
-# Integration
-- [HTTPS and Reverse proxy](https://github.com/kamax-io/mxisd/wiki/HTTPS)
-- [synapse](https://github.com/kamax-io/mxisd/wiki/Homeserver-Integration) as Identity server
-- [synapse with REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth/blob/master/README.md) 
-as authentication module
+## Validate
+Log in using your Matrix client and set `https://example.org` as your Identity server URL, replacing `example.org` by
+the relevant hostname which you configured in your reverse proxy.
+
+Try to invite `mxisd-lookup-test@kamax.io`, which should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io`  
+If it worked, it means you are up and running and can enjoy mxisd in its basic mode! Congratulations!
+
+You can now integrate mxisd further with your infrastructure using the various [features](docs/README.md) guides.
 
 # Support
 ## Community
@@ -225,3 +162,74 @@ For more high-level discussion about the Identity Server architecture/API, go to
 ## Professional
 If you would prefer professional support/custom development for mxisd and/or for Matrix in general, including other open source technologies/products, 
 please visit [our website](https://www.kamax.io/) to get in touch with us and get a quote.
+
+We offer affordable monthly/yearly support plans for mxisd, synapse or your full Matrix infrastructure.
+
+# FAQ
+### Do I need to use mxisd if I run a Homeserver?
+No, but it is recommended, even if you don't use any backends or integration.
+
+mxisd in its default configuration will use federation and involve the central Matrix.org Identity servers when
+performing queries, giving you access to at least the same information than if you were not running it.
+
+It will also give your users a choice to make their 3PIDs available publicly, ensuring they are made aware of the
+privacy consequences, which is not the case with the central Matrix.org servers.
+
+So mxisd is like your gatekeeper and guardian angel. It doesn't change what you already know, just adds some nice
+simple features on top of it. 
+
+### I saw that sydent is the official Identity server implemenation of the Matrix team, I should use that!
+You can, but [sydent](https://github.com/matrix-org/sydent):
+- [was never meant to be self-hosted and should not be done](https://github.com/matrix-org/sydent/issues/22)
+- is not meant to be linked to a specific Homeserver / domain
+- cannot handle federation or proxy lookups, effectively isolating your users from the rest of the network
+- forces you to duplicate all your identity data, so people can be found by 3PIDs
+- forces users to enter all their emails and phone numbers manually in their profile
+
+So really, you should go with mxisd.
+
+### I'm not sure I understand what an "Identity server" is supposed to be or do
+The current Identity service API is more a placeholder, as the Matrix devs did not have time so far to really work on
+what they want to do with that part of the ecosystem. Therefore, "Identity" is a missleading word currently.  
+Given the scope of the current Identity Service API, their would be best called "Directory and Invitation service".
+
+Because the current scope is so limited and no integration is done with the Homeserver, there was a big lack of features
+for groups/corporations/organisation. This is where mxisd comes in.
+
+mxisd implements the Identity Service API and also a set of features which are expected by regular users, truely living
+up to its "Identity server" name.
+
+### So mxisd is just a big hack! I don't want to use non-official features!
+mxisd primary concern is to always be compatible with the Matrix ecosystem and the Identity service API.  
+Whenever the API will be updated and/or enchanced, mxisd will follow, remaining 100% compatible with the ecosystem.
+
+We also directly talk with the Matrix developers to ensure all features we implement have their approval, and that we
+are in line with their vision of Identity management within the Matrix ecosystem.
+
+Therefore, using mxisd is a safe choice. It will be like using the central Matrix.org Identity servers, yet not closing
+the door to very nice enhancements and integrations.
+
+### Should I use mxisd if I don't host my own Homeserver?
+No
+
+# Contribute
+First and foremost, the best way to contribute is to use mxisd and tell us about it!  
+We would love to hear about your experience and get your feedback on how to make it an awesome product. 
+
+You can contribute as a community member by:
+- Opening issues for any weird behaviour or bug. mxisd should feel natural, let us know if it doesn't!
+- Helping us improve the documentation: tell us what is good or not good (in an issue or in Matrix), or make a PR with
+changes you feel improve the doc
+- Contribute code directly: we love contributors! We are quite strict in our reviews but and we'll always review your PR
+in a timely fashion.
+- Donate! any donation is welcome, regardless how small or big. This will directly be used for the fixed costs and
+developer time.
+
+You can contribute as an organisation/corporation by:
+- Get a [support contract](#support-professional). This is the best way you can help us as it ensures mxisd is maintained regularly and you get
+direct access to the support team.
+- Sponsoring new features or bug fixes. We'll quote the cost of development, at a reduced rate, and maintain the code
+in future release of mxisd. (subject to approval of the feature on our end)
+
+# Contact
+Get in touch on Matrix: [#mxisd:kamax.io](https://matrix.to/#/#mxisd:kamax.io)
diff --git a/application.example.yaml b/application.example.yaml
index 864fa03..3158040 100644
--- a/application.example.yaml
+++ b/application.example.yaml
@@ -1,11 +1,6 @@
-# Sample configuration file explaining all possible options, their default value and if they are required or not.
+# Sample configuration file explaining the minimum required keys to be set to run mxisd
 #
-# Any optional configuration item will be prefixed by # (comment character) with the configuration item following
-# directly without any whitespace character.
-# Default values for optional configuration item will also follow such item.
-#
-# Any mandatory configuration item will not be prefixed by # and will also contain a value as example that must be
-# changed. It is advised to re-create a clean config file with only the required configuration item.
+# For a complete list of options, see https://github.com/kamax-io/mxisd
 
 #######################
 # Matrix config items #
@@ -16,48 +11,9 @@
 matrix.domain: ''
 
 
-
-#######################
-# Server config items #
-#######################
-# Indicate on which port the Identity Server will listen.
-#
-# This is be default an unencrypted port.
-# HTTPS can be configured using Tomcat configuration properties.
-#
-#server.port: 8090
-
-
-# Public hostname of this identity server.
-#
-# This would be typically be the same as your Matrix domain.
-# In case it is not, set this value.
-#
-# This value is used in various signatures within the Matrix protocol and should be a reachable hostname.
-# You can validate by ensuring you see a JSON answer when calling (replace the domain):
-# https://example.org/_matrix/identity/status
-#
-#server.name: 'example.org'
-
-
-# Public URL to reach this identity server
-#
-# This is used with 3PID invites in room and other Homeserver key verification workflow.
-# If left unconfigured, it will be generated from the server name.
-#
-# You should typically set this value if you want to change the public port under which
-# this Identity server is reachable.
-#
-# %SERVER_NAME% placeholder is available to avoid configuration duplication.
-# e.g. 'https://%SERVER_NAME%:8443'
-#
-#server.publicUrl: 'https://example.org'
-
-
-
-#############################
-# Signing keys config items #
-#############################
+################
+# Signing keys #
+################
 # Absolute path for the Identity Server signing key.
 # During testing, /var/tmp/mxisd.key is a possible value
 #
@@ -65,278 +21,7 @@ matrix.domain: ''
 #   - /var/opt/mxisd/sign.key
 #   - /var/local/mxisd/sign.key
 #   - /var/lib/mxisd/sign.key
-key.path: '/path/to/sign.key'
-
-
-
-#################################
-# Recurisve lookup config items #
-#################################
-# Configuration items for recursion-type of lookup
-#
-# Lookup access are divided into two types:
-# - Local
-# - Remote
-#
-# This is similar to DNS lookup and recursion and is therefore prone to the same vulnerabilities.
-# By default, only non-public hosts are allowed to perform recursive lookup.
-#
-# This will also prevent very basic endless loops where host A ask host B, which in turn is configured to ask host A,
-# which would then ask host B again, etc.
-
-# Enable recursive lookup globally
-#
-#lookup.recursive.enabled: true
-
-
-# Whitelist of CIDR that will trigger a recursive lookup.
-# The default list includes all private IPv4 address and the IPv6 loopback.
-#
-#lookup.recursive.allowedCidr:
-#  - '127.0.0.0/8'
-#  - '10.0.0.0/8'
-#  - '172.16.0.0/12'
-#  - '192.168.0.0/16'
-#  - '::1/128'
-
-
-# In case no binding is found, query an application server which implements the single lookup end-point
-# to return bridge virtual user that would allow the user to be contacted directly by the said bridge.
-#
-# If a binding is returned, the application server is not expected to sign the message as it is not meant to be
-# reachable from the outside.
-# If a signature is provided, it will be discarded/replaced by this IS implementation (to be implemented).
-#
-# IMPORTANT: This bypass the regular Invite system of the Homeserver. It will be up to the Application Server
-# to handle such invite. Also, if the bridged user were to actually join Matrix later, or if a 3PID binding is found
-# room rights and history would not be transferred, as it would appear as a regular Matrix user to the Homeserver.
-#
-# This configuration is only helpful for Application Services that want to overwrite bridging for 3PID that are
-# handled by the Homeserver. Do not enable unless the Application Server specifically supports it!
-
-# Enable unknown 3PID bridging globally
-#
-#lookup.recursive.bridge.enabled: false
-
-
-# Enable unknown 3PID bridging for hosts that are allowed to perform recursive lookups.
-# Leaving this setting to true is highly recommended in a standard setup, unless this Identity Server
-# is meant to always return a virtual user MXID even for the outside world.
-#
-#lookup.recursive.bridge.recursiveOnly: true
-
-
-# This mechanism can handle the following scenarios:
-#
-# - Single Application Server for all 3PID types: only configure the server value, comment out the rest.
-#
-# - Specific Application Server for some 3PID types, default server for the rest: configure the server value and
-#          each specific 3PID type.
-#
-# - Only specific 3PID types: do not configure the server value or leave it empty/blank, configure each specific
-#          3PID type.
-
-# Default application server to use for all 3PID types. Remove config item or leave empty/blank to disable.
-#
-#lookup.recursive.bridge.server: ''
-
-
-# Configure each 3PID type with a specific application server. Remove config item or leave empty/blank to disable.
-#
-#lookup.recursive.bridge.mappings.email: 'http://localhost:8091'
-#lookup.recursive.bridge.mappings.msisdn: ''
-
-
-
-#####################
-# LDAP config items #
-#####################
-# Global enable/disable switch
-#
-#ldap.enabled: false
-
-
-#### Connection related config items
-# If the connection should be secure
-#
-#ldap.connection.tls: false
-
-
-# Host to connect to
-#
-#ldap.connection.host: 'localhost'
-
-
-# Port to connect to
-#
-#ldap.connection.port: 389
-
-
-# Bind DN for the connection.
-#
-# If Bind DN and password are empty, anonymous authentication is performed
-#
-#ldap.connection.bindDn: 'CN=Matrix Identity Server,CN=Users,DC=example,DC=org'
-
-
-# Bind password for the connection.
-#
-#ldap.connection.bindPassword: 'password'
-
-
-# Base DN used in all queries
-#
-#ldap.connection.baseDn: 'CN=Users,DC=example,DC=org'
-
-
-#### How to map Matrix attributes with LDAP attributes when performing lookup/auth
-#
-# How should we resolve the Matrix ID in case of a match using the attribute.
-#
-# The following type are supported:
-# - uid : the attribute only contains the UID part of the Matrix ID. e.g. 'john.doe' in @john.doe:example.org
-# - mxid : the attribute contains the full Matrix ID - e.g. '@john.doe:example.org'
-#
-#ldap.attribute.uid.type: 'uid'
-
-
-# The attribute containing the binding itself. This value will be used differently depending on the type.
-#
-# /!\ This should match the synapse LDAP Authenticator 'uid' configuration /!\
-#
-# Typical values:
-# - For type 'uid': 'userPrincipalName' or 'uid' or 'saMAccountName'
-# - For type 'mxid', regardless of the directory type, we recommend using 'pager' as it is a standard attribute and
-#   is typically not used.
-#
-#ldap.attribute.uid.value: 'userPrincipalName'
-
-
-# The display name of the user
-#
-#ldap.attribute.name: 'displayName'
-
-
-#### Configuration section relating the authentication of users performed via LDAP.
-#
-# This can be done using the REST Auth module for synapse and pointing it to the identity server.
-# See https://github.com/kamax-io/matrix-synapse-rest-auth
-#
-# During authentication, What to filter potential users by, typically by using a dedicated group.
-# If this value is not set, login check will be performed for all entities within the LDAP
-#
-# Example: (memberOf=CN=Matrix Users,CN=Users,DC=example,DC=org)
-#
-#ldap.auth.filter: ''
-
-
-#### Configuration section relating to identity lookups
-#
-# E-mail query
-#
-#ldap.identity.medium.email: "(|(mailPrimaryAddress=%3pid)(mail=%3pid)(otherMailbox=%3pid))"
-
-
-# Phone numbers query
-#
-# Phone numbers use the MSISDN format: https://en.wikipedia.org/wiki/MSISDN
-# This format does not include international prefix (+ or 00) and therefore has to be put in the query.
-# Adapt this to your needs for each attribute.
-#
-#ldap.identity.medium.msisdn: "(|(telephoneNumber=+%3pid)(mobile=+%3pid)(homePhone=+%3pid)(otherTelephone=+%3pid)(otherMobile=+%3pid)(otherHomePhone=+%3pid))"
-
-
-
-############################
-# SQL Provider config item #
-############################
-#
-# Example configuration to integrate with synapse SQLite DB (default configuration)
-#
-#sql.enabled: true
-#sql.type: 'sqlite'
-#sql.connection: '/var/lib/matrix-synapse/homeserver.db'
-
-
-#
-# Example configuration to integrate with synapse PostgreSQL DB
-#sql.enabled: true
-#sql.type: 'postgresql'
-#sql.connection: '//dnsOrIpToServer/dbName?user=synapseDbUser&password=synapseDbPassword'
-
-
-#
-# Configuration for an arbitrary server with arbitrary driver
-#
-# sql.identity.type possible values:
-# - uid       Returned value is the localpart of the Matrix ID
-# - mxid      Full Matrix ID, including domain
-#
-# sql.identity.query MUST contain a column with label 'uid'
-#
-# If you would like to overwrite the global lookup query for specific medium type,
-# add a config item (see below for example) in the following format
-# sql.identity.medium.theMediumIdYouWant: 'the query'
-
-#sql.enabled: true
-#sql.type: 'jdbcDriverName'
-#sql.connection: '//dnsOrIpToServer/dbName?user=synapseDbUser&password=synapseDbPassword'
-#sql.identity.type: 'mxid'
-#sql.identity.query: 'SELECT raw AS uid FROM table WHERE medium = ? AND address = ?'
-#sql.identity.medium.email: 'SELECT raw AS uid FROM emailTable WHERE address = ?'
-
-
-
-#######################################
-# Lookup queries forward config items #
-#######################################
-# List of forwarders to use to try to match a 3PID.
-#
-# Each server will be tried in the given order, going to the next if no binding was found or an error occurred.
-# These are the current root Identity Servers of the Matrix network.
-#
-#forward.servers:
-#  - "https://matrix.org"
-#  - "https://vector.im"
-
-
-
-###################################
-# 3PID notifications config items #
-###################################
-# If you would like to change the content, see https://github.com/kamax-io/mxisd/blob/master/docs/threepids/notifications/template-generator.md
-#
-#### E-mail invite sender
-#
-# SMTP host
-threepid.medium.email.connectors.smtp.host: "smtp.example.org"
-
-
-# SMTP port
-threepid.medium.email.connectors.smtp.port: 587
-
-
-# TLS mode for the connection.
-#
-# Possible values:
-#  0    Disable TLS entirely
-#  1    Enable TLS if supported by server
-#  2    Force TLS and fail if not available
-#
-#threepid.medium.email.connectors.smtp.tls: 1
-
-
-# Login for SMTP
-threepid.medium.email.connectors.smtp.login: "matrix-identity@example.org"
-
-
-# Password for the account
-threepid.medium.email.connectors.smtp.password: "ThePassword"
-
-
-# The e-mail to send as. If empty, will be the same as login
-threepid.medium.email.identity.from: "matrix-identity@example.org"
-
+key.path: ''
 
 
 ############################
@@ -349,10 +34,7 @@ threepid.medium.email.identity.from: "matrix-identity@example.org"
 #
 #storage.backend: 'sqlite'
 
-
-#### Generic SQLite provider config
-#
-# Path to the SQLite DB file, required if SQLite backend is chosen
+# Path to the SQLite DB file
 #
 # Examples:
 #  - /var/opt/mxisd/mxisd.db
@@ -362,22 +44,53 @@ threepid.medium.email.identity.from: "matrix-identity@example.org"
 storage.provider.sqlite.database: '/path/to/mxisd.db'
 
 
+################
+# LDAP Backend #
+################
+# If you would like to integrate with your AD/Samba/LDAP server,
+# see https://github.com/kamax-io/mxisd/blob/master/docs/backends/ldap.md
 
-######################
-# DNS-related config #
-######################
-# The domain to overwrite
+###############
+# SQL Backend #
+###############
+# If you would like to integrate with a MySQL/MariaDB/PostgreQL/SQLite DB,
+# see https://github.com/kamax-io/mxisd/blob/master/docs/backends/sql.md
+
+################
+# REST Backend #
+################
+# If you would like to integrate with an existing web service/webapp,
+# see https://github.com/kamax-io/mxisd/blob/master/docs/backends/rest.md
+
+
+#################################################
+# Notifications for invites/addition to profile #
+#################################################
+# If you would like to change the content,
+# see https://github.com/kamax-io/mxisd/blob/master/docs/threepids/notifications/template-generator.md
 #
-#dns.overwrite.homeserver.name: 'example.org'
-
-
-# - 'env' from environment variable specified by value
-# - any other value will use the value as-is as host
+#### E-mail invite sender
 #
-#dns.overwrite.homeserver.type: 'raw'
+# SMTP host
+threepid.medium.email.connectors.smtp.host: "smtp.example.org"
 
+# SMTP port
+threepid.medium.email.connectors.smtp.port: 587
 
-# The value to use, depending on the type.
-# Protocol will always be HTTPS
+# TLS mode for the connection.
 #
-#dns.overwrite.homeserver.value: 'localhost:8448'
+# Possible values:
+#  0    Disable TLS entirely
+#  1    Enable TLS if supported by server (default)
+#  2    Force TLS and fail if not available
+#
+#threepid.medium.email.connectors.smtp.tls: 1
+
+# Login for SMTP
+threepid.medium.email.connectors.smtp.login: "matrix-identity@example.org"
+
+# Password for the account
+threepid.medium.email.connectors.smtp.password: "ThePassword"
+
+# The e-mail to send as. If empty, will be the same as login
+threepid.medium.email.identity.from: "matrix-identity@example.org"
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..4e8b95e
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,24 @@
+# Table of Contents
+
+- Installation
+  - [Debian package](install/debian.md)
+  - [Docker](install/docker.md)
+- [Build from source](build.md)
+- [Configuration](configure.md)
+- Features
+  - [Matrix Identity Service](features/identity.md)
+  - [Homeserver Authentication](features/authentication.md)
+  - [Directory seach](features/directory-users.md)
+  - [Identity server Federation](features/federation.md)
+  - [Bridge integration](features/bridge-integration.md)
+- Backends
+  - [LDAP](backends/ldap.md)
+  - [SQL](backends/sql.md)
+  - [REST](backends/rest.md)
+  - [Google Firebase](backends/firebase.md)
+- Notifications
+  - Handlers
+    - [Basic](threepids/notifications/basic-handler.md)
+    - [SendGrid](threepids/notifications/sendgrid-handler.md)
+- [Sessions](sessions/3pid.md)
+  - [Views](sessions/3pid-views.md)
diff --git a/docs/backends/firebase.md b/docs/backends/firebase.md
new file mode 100644
index 0000000..a9e00d7
--- /dev/null
+++ b/docs/backends/firebase.md
@@ -0,0 +1,9 @@
+# Google Firebase
+## Configuration
+To be completed. For now, see default structure and values:
+```
+firebase:
+  enabled: false
+  credentials: '/path/to/firebase/credentials.json'
+  database: 'https://my-project.firebaseio.com/'
+```
\ No newline at end of file
diff --git a/docs/backends/ldap.md b/docs/backends/ldap.md
new file mode 100644
index 0000000..6f45f55
--- /dev/null
+++ b/docs/backends/ldap.md
@@ -0,0 +1,86 @@
+# AD/Samba/LDAP backend
+## Configuration
+### Structure and default values
+```
+ldap:
+  enabled: false
+  filter: ''
+  connection:
+    host: ''
+    tls: false
+    port: 389
+    bindDn: ''
+    bindPassword: ''
+    baseDn: ''
+  attribute:
+    uid:
+      type: 'uid'
+      value: 'userPrincipalName'
+    name: 'displayName'
+    threepid:
+      email:
+        - 'mailPrimaryAddress'
+        - 'mail'
+        - 'otherMailbox'
+      msisdn:
+        - 'telephoneNumber'
+        - 'mobile'
+        - 'homePhone'
+        - 'otherTelephone'
+        - 'otherMobile'
+        - 'otherHomePhone'
+  auth:
+    filter: ''
+  directory:
+    attribute:
+      other: []
+    filter: ''
+  identity:
+    filter: ''
+    medium:
+      email: ''
+      msisdn: ''
+```
+### General
+| Item      | Description                                                                               |
+|-----------|-------------------------------------------------------------------------------------------|
+| `enabled` | Globaly enable/disable the LDAP backend                                                   |
+| `filter`  | Global filter to apply on all LDAP queries. Can be overwritten in each applicable section |
+
+### Connection
+| Item           | Description                                          |
+|----------------|------------------------------------------------------|
+| `host`         | Host to connect to                                   |
+| `port`         | Port to use                                          |
+| `tls`          | boolean to use TLS or not (STARTLS is not supported) |
+| `bindDn`       | Bind DN for authentication                           |
+| `bindPassword` | Bind password                                        |
+| `baseDn`       | Base DN for queries                                  |
+
+### Attributes
+| Item        | Description                                                                                                            |
+|-------------|------------------------------------------------------------------------------------------------------------------------|
+| `uid.type`  | Indicate how to process the User ID (UID) attribute:                                                                   |
+|             |   - `uid` will consider the value as the [Localpart](https://matrix.org/docs/spec/intro.html#user-identifiers)         |
+|             |   - `mxid` will consider the value as a complete [Matrix ID](https://matrix.org/docs/spec/intro.html#user-identifiers) |
+| `uid.value` | Attribute name refering to the User ID. This is typically `userPrincipalName` on AD/Samba setups and `uid` in LDAP     |
+| `name`      | Attribute name that contains the [Display Name](https://matrix.org/docs/spec/intro.html#profiles) of the user          |
+| `threepid`  | Namespace where each key is a 3PID type and contains a list of attributes                                              |
+
+### Authentication
+| Item     | Description                                                                                      |
+|----------|--------------------------------------------------------------------------------------------------|
+| `filter` | Specific user filter applied during authentication. Global filter is used if empty/blank/not set |
+
+### Directory
+| Item              | Description                                                         |
+|-------------------|---------------------------------------------------------------------|
+| `attribute.other` | Additional attributes to be used when performing directory searches |
+| `filter`          | Specific user filter applied during directory search.               |
+|                   | Global filter is used if empty/blank/not set                        |
+
+### Identity
+| Item     | Description                                                                                       |
+|----------|---------------------------------------------------------------------------------------------------|
+| `filter` | Specific user filter applied during identity search. Global filter is used if empty/blank/not set | 
+| `medium` | Namespace to overwrite generated queries from the list of attributes for each 3PID medium         |
diff --git a/docs/backends/sql.md b/docs/backends/sql.md
new file mode 100644
index 0000000..ee0866e
--- /dev/null
+++ b/docs/backends/sql.md
@@ -0,0 +1,23 @@
+# SQL Backend
+## Configuration
+To be completed. For now, see default structure and values:
+```
+sql:
+  enabled: false
+  type: 'sqlite' or 'postgresql'
+  connection: ''
+  auth:
+    enabled: false
+  directory:
+    enabled: false
+    query:
+      name:
+        type: 'localpart'
+        value: 'SELECT 1'
+      threepid:
+        type: 'localpart'
+        value: 'SELECT 1'
+  identity:
+    type: 'localpart'
+    query: 'SELECT user_id AS uid FROM user_threepids WHERE medium = ? AND address = ?'
+```
diff --git a/docs/build.md b/docs/build.md
new file mode 100644
index 0000000..3ff3785
--- /dev/null
+++ b/docs/build.md
@@ -0,0 +1,105 @@
+# From source
+- [Binaries](#binaries)
+- [Debian package](#debian-package)
+- [Docker image](#docker-image)
+
+## Binaires
+### Requirements
+- JDK 1.8
+
+### Build
+```
+git clone https://github.com/kamax-io/mxisd.git
+cd mxisd
+./gradlew build
+```
+
+Create a new configuration file by coping `application.example.yaml` to `application.yaml` and edit to your needs.  
+For advanced configuration, see the [Configure section](configure.md).
+
+Start the server in foreground to validate the build and configuration:
+```
+java -jar build/libs/mxisd.jar
+```
+
+Ensure the signing key is available:
+```
+$ curl 'http://localhost:8090/_matrix/identity/api/v1/pubkey/ed25519:0'
+{"public_key":"..."}
+```
+
+Test basic recursive lookup (requires Internet connection with access to TCP 443):
+```
+$ curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=mxisd-lookup-test@kamax.io'
+{"address":"mxisd-lookup-test@kamax.io","medium":"email","mxid":"@mxisd-lookup-test:kamax.io",...}
+```
+
+If you enabled LDAP, you can also validate your config with a similar request after replacing the `address` value with
+something present within your LDAP
+```
+curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=john.doe@example.org'
+```
+
+If you plan on testing the integration with a homeserver, you will need to run an HTTPS reverse proxy in front of it
+as the reference Home Server implementation [synapse](https://github.com/matrix-org/synapse) requires a HTTPS connection
+to an ID server.  
+See the [Integration section](#integration) for more details.
+
+### Install
+1. Prepare files and directories:
+```
+# Create a dedicated user
+useradd -r mxisd
+
+# Create bin directory
+mkdir /opt/mxisd
+
+# Create config directory and set ownership
+mkdir /etc/opt/mxisd
+chown mxisd /etc/opt/mxisd
+
+# Create data directory and set ownership
+mkdir /var/opt/mxisd
+chown mxisd /var/opt/mxisd
+
+# Copy <repo root>/build/libs/mxisd.jar to bin directory
+cp ./build/libs/mxisd.jar /opt/mxisd/
+chown mxisd /opt/mxisd/mxisd.jar
+chmod a+x /opt/mxisd/mxisd.jar
+
+# Create symlink for easy exec
+ln -s /opt/mxisd/mxisd.jar /usr/bin/mxisd
+```
+
+2. Copy the sample config file `./application.example.yaml` to `/etc/opt/mxisd/mxisd.yaml`, edit to your needs
+4. Copy `<repo root>/src/systemd/mxisd.service` to `/etc/systemd/system/` and edit if needed
+5. Enable service for auto-startup
+```
+systemctl enable mxisd
+```
+6. Start mxisd
+```
+systemctl start mxisd
+```
+
+## Debian package
+### Requirements
+- fakeroot
+- dpkg-deb
+
+### Build
+[Build mxisd](#build) then:
+```
+./gradlew buildDeb 
+```
+You will find the debian package in `build/dist`
+
+## Docker image
+[Build mxisd](#build) then:
+```
+./gradlew dockerBuild
+```
+You can run a container of the given image and test it with the following command (adapt volumes host paths):
+```
+docker run -v /data/mxisd/etc:/etc/mxisd -v /data/mxisd/var:/var/mxisd -p 8090:8090 -t kamax/mxisd:latest-dev
+```
diff --git a/docs/configure.md b/docs/configure.md
new file mode 100644
index 0000000..aa14991
--- /dev/null
+++ b/docs/configure.md
@@ -0,0 +1,183 @@
+# Configuration
+- [Syntax](#syntax)
+- [Variables](#variables)
+- [Categories](#categories)
+
+## Syntax
+The configuration file is YAML based, allowing two types of syntax.
+
+Properties-like:
+```
+my.config.item: 'value'
+```
+
+Object-like:
+```
+my:
+  config:
+    item: 'value'
+
+```
+These can also be combined within the same file.  
+Both syntax will be used interchangeably in these documents.
+
+Default values for each possible option are documented [here](../src/main/resources/application.yaml)
+
+## Variables
+It is possible to copy the value of a configuration item into another using the syntax `${config.key.item}`.  
+Example that will copy the value of `matrix.domain` into `server.name`:
+```
+matrix:
+  domain: 'example.org'
+
+server:
+  name: '${matrix.domain}'
+```
+
+**WARNING:** mxisd might overwrite/adapt some values during launch. Those changes will not be reflected into copied keys.
+
+## Categories
+For each category below, the base configuration path will be given, which needs to be appened to every configuration
+item described.
+
+Example: if the base path was `basePath` and the following table was given:
+
+| Name | Purpose |
+|------|---------|
+| item1 | To give an example |
+| item2 | To give another example |
+
+The following configurations could be used, all being equivalent:
+```
+basePath.item1: 'myValue'
+basePath.item2: 'myOtherValue'
+```
+```
+basePath:
+  item1: 'myValue'
+  item2: 'myOtherValue'
+```
+```
+basePath.item1: 'myValue'
+basePath:
+  item2: 'myOtherValue'
+```
+
+---
+
+In case a relative base path is given, it is appended to the one above.
+
+Example: With base path `basePath`, the relative base `relativeBasePath` and the following table:
+  
+| Name | Purpose |
+|------|---------|
+| item1 | To give an example |
+| item2 | To give another example |
+
+The following configurations could be used, all being equivalent:
+```
+basePath.relativeBasePath.item1: 'myValue'
+basePath.relativeBasePath.item2: 'myOtherValue'
+```
+```
+basePath:
+  relativeBasePath:
+    item1: 'myValue'
+    item2: 'myOtherValue'
+```
+```
+basePath.relativeBasePath.item1: 'myValue'
+basePath:
+  relativeBasePath:
+    item2: 'myOtherValue'
+```
+
+### Matrix
+Base path: `matrix`
+
+| Name | Purpose |
+|------|---------|
+| `domain` | Matrix domain name, same as the Homeserver, used to build appropriate Matrix IDs |
+
+---
+
+Relative base path: `identity`
+
+| Name | Purpose |
+|------|---------|
+| `servers` | Namespace to create arbitrary list of Identity servers, usable in other parts of the configuration |
+
+Example:
+```
+matrix.identity.servers:
+  root:
+    - 'https://matrix.org'
+```
+Create a list under the label `root` containing a single Identity server, `https://matrix.org`
+### Server
+| Name | Purpose |
+|------|---------|
+| `name` | Public hostname of mxisd, if different from the Matrix domain |
+| `port` | HTTP port to listen on (unencrypted) |
+| `publicUrl` | Defaults to `https://${server.name}` |
+
+### Storage
+Base path: `storage`
+
+| Name | Purpose |
+|------|---------|
+| `backend` | Specify which SQL backend to use. only `sqlite` is currently supported. |
+
+---
+Relative base path: `provider.sqlite`
+
+| Name | Purpose |
+|------|---------|
+| `database` | Absolute location of the SQLite database |
+
+### Backends
+- [LDAP](backends/ldap.md)
+- [SQL](backends/sql.md)
+- [REST](backends/rest.md)
+- [Google Firebase](backends/firebase.md)
+
+### Lookups
+work in progress, should not be configured.
+
+### Sessions
+See the [dedicated document](sessions/3pid.md)
+
+### Notifications
+Base path: `notification`
+
+| Name | Purpose |
+|------|---------|
+| handler | Namespace to specify the handler to use for each 3PID |
+| handlers | Namespace used by individual handlers for their own configuration |
+
+Example:
+```
+notification:
+  handler:
+    email: 'sendgrid'
+    msisdn: 'raw'
+  handlers:
+    raw:
+      ...
+    sendgrid:
+      ...
+```
+- Emails notifications would use the `sendgrid` handler, which define its own configuration user `handlers.sendgrid`
+- Phone notification would use the `raw` handler, basic default built-in handler of mxisd
+#### Handlers
+Relative base path: `handlers`
+
+Built-in:
+- [Basic](threepids/notifications/basic-handler.md)
+- [SendGrid](threepids/notifications/sendgrid-handler.md)
+
+### Views
+See the [dedicated document](sessions/3pid-views.md)
+
+### DNS Overwite
+Specific to other features.
diff --git a/docs/features/authentication.md b/docs/features/authentication.md
new file mode 100644
index 0000000..d79a030
--- /dev/null
+++ b/docs/features/authentication.md
@@ -0,0 +1,7 @@
+# Authentication
+Performed via [synapse with REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth/blob/master/README.md)
+
+Point the `endpoint` to mxisd internal IP on port 8090
+
+## Profile auto-fill
+To be documented
\ No newline at end of file
diff --git a/docs/features/bridge-integration.md b/docs/features/bridge-integration.md
new file mode 100644
index 0000000..6d5d76c
--- /dev/null
+++ b/docs/features/bridge-integration.md
@@ -0,0 +1 @@
+To be documented
diff --git a/docs/features/directory-users.md b/docs/features/directory-users.md
index 327adcd..0af84d8 100644
--- a/docs/features/directory-users.md
+++ b/docs/features/directory-users.md
@@ -89,8 +89,7 @@ the `matrix.domain` configuration option and avoid duplicating it.
 
 ### Backends
 #### LDAP
-Configuration structure has been altered so queries are automatically built from a global or specific filter and a list
-of attributes. To ensure Directory feature works, here how the LDAP configuration should look like:
+To ensure Directory feature works, here's how the LDAP configuration should look like:
 ```
 ldap:
   enabled: false
@@ -123,12 +122,12 @@ ldap:
         - 'employeeNumber'
         - 'someOtherAttribute'
 ```
-Previous configuration entries that contained queries with the `%3pid` placeholder should not be used anymore, unless
-specifically overwritten. Instead, add all attributes to the relevant sections.
+Only include the `attribute` sub-sections if you would like to set another value. Else, it is best not to include them
+to inherit the default values.
 
 If you would like to include an attribute which is not a display name or a 3PID, you can use the
-`directory.attribute.other` to list any extra attributes you want included in searches.  
-If you do not want to include any extra attribute, that configuration section can be skipped. 
+`directory.attribute.other` to list any extra attributes you want included in searches. If you do not want to include
+any extra attribute, that configuration section can be skipped. 
 
 #### SQL
 If you plan to integrate directory search directly with synapse, use the `synapseSql` provider, based on the following
@@ -137,9 +136,9 @@ config:
 synapseSql:
   enabled: true
   type: <database ID>
-  connection: ``
+  connection: '<connection info>'
 ```
-`type` and `connection`, including any other configuration item, follow the same values as the regular `sql` backend.
+`type` and `connection`, including any other configuration item, follow the same values as the regular [SQL backend](../backends/sql.md).
 
 ---
 
diff --git a/docs/features/federation.md b/docs/features/federation.md
new file mode 100644
index 0000000..71319bd
--- /dev/null
+++ b/docs/features/federation.md
@@ -0,0 +1,15 @@
+# Identity service Federation
+To allow other federated Identity Server to reach yours, the same algorithm used for Homeservers takes place:
+1. Check for the appropriate DNS SRV record
+2. If not found, use the base domain
+ 
+If your Identity Server public hostname does not match your Matrix domain, configure the following DNS SRV entry 
+and replace `matrix.example.com` by your Identity server public hostname - **Make sure to end with a final dot!**
+```
+_matrix-identity._tcp.example.com. 3600 IN SRV 10 0 443 matrix.example.com.
+``` 
+This would only apply for 3PID that are DNS-based, like e-mails. For anything else, like phone numbers, no federation 
+is currently possible.  
+
+The port must be HTTPS capable. Typically, TCP port `8090` of mxisd should be behind a reverse proxy which does HTTPS.
+See the [main README integration section](../README.md#integration) for more details.
diff --git a/docs/features/identity.md b/docs/features/identity.md
new file mode 100644
index 0000000..2b5fa3e
--- /dev/null
+++ b/docs/features/identity.md
@@ -0,0 +1,3 @@
+To be documented.
+
+Implementation of the [Matrix Identity service API](https://matrix.org/docs/spec/identity_service/unstable.html)
diff --git a/docs/install/debian.md b/docs/install/debian.md
new file mode 100644
index 0000000..95e3aae
--- /dev/null
+++ b/docs/install/debian.md
@@ -0,0 +1,39 @@
+# Debian package
+## Install
+1. Donwload the [latest release](https://github.com/kamax-io/mxisd/releases/latest)
+2. Run:
+```
+dpkg -i /path/to/downloaded/mxisd.deb
+```
+## Files
+| Location                          | Purpose                                      |
+|-----------------------------------|----------------------------------------------|
+| /etc/mxisd                        | Configuration directory                      |
+| /etc/mxisd/mxisd.yaml             | Main configuration file                      |
+| /etc/mxisd/signing.key            | Default location for mxisd signing keys      |
+| /etc/systemd/system/mxisd.service | Systemd configuration file for mxisd service |
+| /usr/lib/mxisd                    | Binairies                                    |
+| /var/lib/mxisd                    | Data                                         |
+
+## Control
+Start mxisd using:
+```
+sudo systemctl start mxisd
+```
+
+Stop mxisd using:
+```
+sudo systemctl stop mxisd
+```
+
+## Troubleshoot
+All logs are sent to `STDOUT` which are saved in `/var/log/syslog` by default.  
+You can:
+- grep & tail using `mxisd`:
+```
+tail -n 99 -f /var/log/syslog | grep mxisd
+```
+- use Systemd's journal:
+```
+journalctl -f n 99 -u mxisd
+```
diff --git a/docs/install/docker.md b/docs/install/docker.md
new file mode 100644
index 0000000..1e8b88f
--- /dev/null
+++ b/docs/install/docker.md
@@ -0,0 +1,14 @@
+# Docker
+## Fetch
+Pull the latest stable image:
+```
+docker pull kamax/mxisd
+```
+
+## Run
+Run it (adapt volume paths to your host):
+```
+docker run --rm -v /data/mxisd/etc:/etc/mxisd -v /data/mxisd/var:/var/mxisd -p 8090:8090 -t kamax/mxisd
+```
+
+For more info, including the list of possible tags, see [the public repository](https://hub.docker.com/r/kamax/mxisd/)
diff --git a/docs/sessions/3pid.md b/docs/sessions/3pid.md
index 59299bd..2e48643 100644
--- a/docs/sessions/3pid.md
+++ b/docs/sessions/3pid.md
@@ -17,7 +17,7 @@
     - [Sessions disabled](#sessions-disabled)
 
 ## Overview
-When adding an email, a phone number or any other kind of 3PID (Third-Party Identifier), 
+When adding an email, a phone number or any other kind of 3PID (Third-Party Identifier) in a Matrix client, 
 the identity server is called to validate the 3PID.
 
 Once this 3PID is validated, the Homeserver will publish the user Matrix ID on the Identity Server and
diff --git a/docs/threepids/notifications/basic-handler.md b/docs/threepids/notifications/basic-handler.md
new file mode 100644
index 0000000..b2fe8d7
--- /dev/null
+++ b/docs/threepids/notifications/basic-handler.md
@@ -0,0 +1,66 @@
+# Basic Notification handler
+Basic notification handler which uses two components:
+- Content generator, to produce the notifications
+- Connectors to send the notification content
+
+This handler can be used with the 3PID types:
+- `email`
+- `msisdn` (Phone numbers)
+
+## Generators
+- [Template](template-generator.md)
+## Connectors
+- Email
+  - [SMTP](../medium/email/smtp-connector.md)
+- SMS
+  - [Twilio](../medium/msisdn/twilio-connector.md)
+
+## Configuration
+Enabled by default or with:
+```
+notification:
+  handler:
+    email: 'raw'
+```
+
+**WARNING:** Will be consolidated soon, prone to breaking changes.  
+Structure and default values:
+```
+threepid:
+  medium:
+    email:
+      identity:
+        from: ''
+        name: ''
+      connector: 'smtp'
+      generator: 'template'
+      connectors:
+        smtp:
+          host: ''
+          port: 587
+          tls: 1
+          login: ''
+          password: ''
+      generators:
+        template:
+          invite: 'classpath:threepids/email/invite-template.eml'
+          session:
+            validation:
+              local: 'classpath:threepids/email/validate-local-template.eml'
+              remote: 'classpath:threepids/email/validate-remote-template.eml'
+    msisdn:
+      connector: 'twilio'
+      generator: 'template'
+      connectors:
+        twilio:
+          accountSid: ''
+          authToken: ''
+          number: ''
+      generators:
+        template:
+          invite: 'classpath:threepids/sms/invite-template.txt'
+          session:
+            validation:
+              local: 'classpath:threepids/sms/validate-local-template.txt'
+              remote: 'classpath:threepids/sms/validate-remote-template.txt'
+```
diff --git a/docs/threepids/notifications/sendgrid-handler.md b/docs/threepids/notifications/sendgrid-handler.md
new file mode 100644
index 0000000..a291f92
--- /dev/null
+++ b/docs/threepids/notifications/sendgrid-handler.md
@@ -0,0 +1,9 @@
+# SendGrid Notification handler
+To be completed. See [raw possible configuration items](https://github.com/kamax-io/mxisd/blob/master/src/main/resources/application.yaml#L172).
+
+Enabled with:
+```
+notification:
+  handler:
+    email: 'sendgrid'
+```
\ No newline at end of file
diff --git a/docs/threepids/notifications/template-generator.md b/docs/threepids/notifications/template-generator.md
index e2acc0a..a48d8e4 100644
--- a/docs/threepids/notifications/template-generator.md
+++ b/docs/threepids/notifications/template-generator.md
@@ -64,7 +64,7 @@ This template is used when to user which added their 3PID address to their profi
 allows remote sessions.
 
 **NOTE:** 3PID session always require local validation of a token, even if a remote session is enforced.  
-One cannot bind a MXID to the session until both local and remote sessions have been validated.
+One cannot bind a Matrix ID to the session until both local and remote sessions have been validated.
 
 #### Placeholders
 | Placeholder          | Purpose                                                |
diff --git a/src/main/java/io/kamax/mxisd/config/ldap/LdapIdentityConfig.java b/src/main/java/io/kamax/mxisd/config/ldap/LdapIdentityConfig.java
index 8bc4110..7d78886 100644
--- a/src/main/java/io/kamax/mxisd/config/ldap/LdapIdentityConfig.java
+++ b/src/main/java/io/kamax/mxisd/config/ldap/LdapIdentityConfig.java
@@ -32,7 +32,7 @@ import java.util.Optional;
 public class LdapIdentityConfig {
 
     private String filter;
-    private String token = "%3pid";
+    private String token;
     private Map<String, String> medium = new HashMap<>();
 
     public String getFilter() {
diff --git a/src/main/resources/application.yaml b/src/main/resources/application.yaml
index 5c0abd9..ed374a6 100644
--- a/src/main/resources/application.yaml
+++ b/src/main/resources/application.yaml
@@ -5,10 +5,10 @@ spring:
 logging:
   level:
     org:
-      springframework: "WARN"
+      springframework: 'WARN'
       apache:
-        catalina: "WARN"
-        directory: "WARN"
+        catalina: 'WARN'
+        directory: 'WARN'
   pattern:
     console: '%d{yyyy-MM-dd HH:mm:ss.SSS} ${LOG_LEVEL_PATTERN:%5p} [%15.15t] %35.35logger{34} : %m%n${LOG_EXCEPTION_CONVERSION_WORD:%wEx}'
 
@@ -16,6 +16,7 @@ server:
   port: 8090
 
 matrix:
+  domain: ''
   identity:
     servers:
       root:
@@ -47,8 +48,12 @@ ldap:
   enabled: false
   filter: ''
   connection:
+    host: ''
     tls: false
     port: 389
+    bindDn: ''
+    bindPassword: ''
+    baseDn: ''
   attribute:
     uid:
       type: 'uid'
@@ -74,6 +79,7 @@ ldap:
     filter: ''
   identity:
     filter: ''
+    token: '%3pid'
     medium:
       email: ''
       msisdn: ''
@@ -81,6 +87,7 @@ ldap:
 firebase:
   enabled: false
 
+
 sql:
   enabled: false
   type: 'sqlite'
@@ -106,8 +113,8 @@ synapseSql:
 
 forward:
   servers:
-    - "https://matrix.org"
-    - "https://vector.im"
+    - 'https://matrix.org'
+    - 'https://vector.im'
 
 threepid:
   medium: