diff --git a/doc/Home.md b/doc/Home.md
index d1194a2b6e..cd8752c1ef 100644
--- a/doc/Home.md
+++ b/doc/Home.md
@@ -30,6 +30,7 @@ Friendica Documentation and Resources
 * [Install](help/Install)
 * [Settings](help/Settings)
 * [Installing Connectors (Twitter/GNU Social)](help/Installing-Connectors)
+* [Install an ejabberd server (XMPP chat) with synchronized credentials](help/install-ejabberd)
 * [Message Flow](help/Message-Flow)
 * [Using SSL with Friendica](help/SSL)
 * [Twitter/GNU Social API Functions](help/api)
diff --git a/doc/de/Home.md b/doc/de/Home.md
index 17e4b7dc29..2a9ea091ed 100644
--- a/doc/de/Home.md
+++ b/doc/de/Home.md
@@ -32,6 +32,7 @@ Friendica - Dokumentation und Ressourcen
 * [Konfigurationen](help/Settings)
 * [Plugins](help/Plugins)
 * [Konnektoren (Connectors) installieren (Twitter/GNU Social)](help/Installing-Connectors)
+* [Installation eines ejabberd Servers (XMPP-Chat) mit synchronisierten Anmeldedaten](help/install-ejabberd) (EN)
 * [Nachrichtenfluss](help/Message-Flow)
 * [Betreibe deine Seite mit einem SSL-Zertifikat](help/SSL)
 * [Entwickler](help/Developers)
diff --git a/doc/install-ejabberd.md b/doc/install-ejabberd.md
new file mode 100644
index 0000000000..c99a845500
--- /dev/null
+++ b/doc/install-ejabberd.md
@@ -0,0 +1,45 @@
+Install an ejabberd with synchronized credentials
+=================================================
+
+* [Home](help)
+
+[Ejabberd](https://www.ejabberd.im/) is a chat server that uses XMPP as messaging protocol that you can use with a large amount of clients. In conjunction 
+with the "xmpp" addon it can be used for a web based chat solution for your users.
+
+Installation
+------------
+
+- Change it's owner to whichever user is running the server, ie. ejabberd
+
+        $ chown ejabberd:ejabberd /path/to/friendica/include/auth_ejabberd.php
+
+- Change the access mode so it is readable only to the user ejabberd and has exec
+
+        $ chmod 700 /path/to/friendica/include/auth_ejabberd.php
+
+- Edit your ejabberd.cfg file, comment out your auth_method and add:
+
+        {auth_method, external}.
+        {extauth_program, "/path/to/friendica/include/auth_ejabberd.php"}.
+
+- Disable the module "mod_register" and disable the registration:
+
+        {access, register, [{deny, all}]}.
+
+- Enable BOSH:
+  - Enable the module "mod_http_bind"
+  - Edit this line:
+
+        {5280, ejabberd_http,    [captcha, http_poll, http_bind]}
+
+  - In your apache configuration for your site add this line:
+
+        ProxyPass /http-bind http://127.0.0.1:5280/http-bind retry=0
+
+- Restart your ejabberd service, you should be able to login with your friendica credentials
+
+Other hints
+-----------
+- if a user has a space or a @ in the nickname, the user has to replace these characters:
+  - " " (space) is replaced with "%20"
+  - "@" is replaced with "(a)"
diff --git a/doc/readme.md b/doc/readme.md
index a5eeb54511..068d0c9c5c 100644
--- a/doc/readme.md
+++ b/doc/readme.md
@@ -30,6 +30,7 @@ Friendica Documentation and Resources
 * [Settings](help/Settings)
 * [Plugins](help/Plugins)
 * [Installing Connectors (Twitter/GNU Social)](help/Installing-Connectors)
+* [Install an ejabberd server (XMPP chat) with synchronized credentials](help/install-ejabberd)
 * [Message Flow](help/Message-Flow)
 * [Using SSL with Friendica](help/SSL)
 * [Developers](help/Developers)