Add setup diagram to docs

66ef67a5 · JC Brand · 9008a1d4 · 66ef67a5 · 66ef67a5 · 66ef67a5
Commit 66ef67a5 authored Sep 04, 2017 by JC Brand
Showing with 34 additions and 18 deletions

docs/source/images/diagram.png docs/source/images/diagram.png +0 -0

docs/source/images/diagram.xml docs/source/images/diagram.xml +1 -0

docs/source/setup.rst docs/source/setup.rst +33 -18

No files found.
--- a/docs/source/images/diagram.png
+++ b/docs/source/images/diagram.png
--- a/docs/source/images/diagram.xml
+++ b/docs/source/images/diagram.xml
+<mxfile userAgent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:55.0) Gecko/20100101 Firefox/55.0" version="7.3.5" editor="www.draw.io" type="device"><diagram name="Page-1" id="e3a06f82-3646-2815-327d-82caf3d4e204">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</diagram></mxfile>
\ No newline at end of file
--- a/docs/source/setup.rst
+++ b/docs/source/setup.rst
@@ -12,22 +12,37 @@ Setup and integration
 What you will need
 ------------------

-If you'd like to host your own version of converse.js or you would like to
-integrate it into your website, then you'll need to set up and configure some
-more server components.
+If you'd like to host your own version of Converse.js or you would like to
+integrate it into your website, then you'll need to do some further setup work.

-For example, if you want to allow chat accounts under your own domain (for
-example, the same domain as your website), then you will need to set up your
-own :ref:`XMPP server`.
+For example, if you want to allow chat accounts under your own domain (i.e.
+the same domain as your website), then you will need to set up your
+own :ref:`XMPP server` that hosts accounts under that domain.

-Besides an XMPP server, you also need a way for converse.js (which uses HTTP), to
-communicate with XMPP servers (which use XMPP).
+Besides an XMPP server, you'll also need a way for Converse.js (which uses HTTP
+or Websocket), to communicate with the XMPP server(s).

-For this, you'll need :ref:`BOSH Connection Manager`.
+Here you have two choices. You can either use a :ref:`BOSH Connection Manager`
+(standalone or integrated into the XMPP server) which allows you to use the
+XMPP protocol over HTTP, or you can use a websocket connection if your XMPP
+server supports it.
+
+Furthermore, it's possible to let users who are authenticated against your web
+application to also automatically be logged in to the XMPP server.
+
+There are various ways in which this can be achived. One way of doing this is
+to use a directory service such as LDAP or Active Directory and to share it
+between your backend web application and your XMPP server. The diagram below
+assumes such a setup.
+
+For other options, please read the section: :ref:`session-support`.
+
+.. figure:: images/diagram.png
+   :align: center
+   :alt: A diagram of a possible setup, consisting of Converse.js, a web server, a backend web application, an XMPP server, a user directory such as LDAP and an XMPP server.
+
+   This diagram shows a potential setup containing various services (image generated with `draw.io <https://draw.io>`_).

-Lastly, if you want to maintain a single chat session for your website's users,
-you'll need to set up a BOSH session on your server, which converse.js can then
-connect to once the page loads. Please see the section: :ref:`session-support`.

 .. _`XMPP server`:

@@ -36,14 +51,13 @@ An XMPP server

 *Converse.js* implements `XMPP <http://xmpp.org/about-xmpp/>`_ as its
 messaging protocol, and therefore needs to connect to an XMPP/Jabber
-server (Jabber is really just a synonym for XMPP).
+server (Jabber® is an older and more user-friendly synonym for XMPP).

 You can connect to public XMPP servers like ``jabber.org`` but if you want to
 have :ref:`session support <session-support>` you'll have to set up your own XMPP server.

-You can find a list of public XMPP servers/providers on `xmpp.net <http://xmpp.net>`_ and a list of
-servers that you can set up yourself on `xmpp.org <http://xmpp.org/xmpp-software/servers/>`_.
-
+You can find a list of public XMPP servers/providers on `xmpp.net <https://list.jabber.at>`_
+and a list of servers that you can set up yourself on `xmpp.org <http://xmpp.org/xmpp-software/servers/>`_.

 .. _`BOSH connection manager`:

@@ -51,10 +65,11 @@ A BOSH Connection Manager
 =========================

 Your website and *Converse.js* use `HTTP <https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol>`_
-as protocol to communicate with the webserver. HTTP connections are stateless and usually shortlived.
+as protocol to communicate with the webserver. HTTP connections are
+stateless and usually shortlived.

 XMPP on the other hand, is the protocol that enables instant messaging, and
-its connections are stateful and usually longer.
+its connections are stateful and usually last much longer.

 To enable a web application like *Converse.js* to communicate with an XMPP
 server, we need a proxy which acts as a bridge between these two protocols.