Add setup diagram to docs
This commit is contained in:
parent
9008a1d4d4
commit
66ef67a589
BIN
docs/source/images/diagram.png
Normal file
BIN
docs/source/images/diagram.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 81 KiB |
1
docs/source/images/diagram.xml
Normal file
1
docs/source/images/diagram.xml
Normal file
|
@ -0,0 +1 @@
|
||||||
|
<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">7Vtbc5s4FP41ntl9KKMLuj3GTi8P6Wx28tDuU0cG2abFyAMkcfrrVwJhA8Kxk+Jsmll3xrWOhCS+8+k7R4JM8Gy9/ZjLzeqzjlU6QSDeTvDlBCEREvNtDQ+1gQhQG5Z5EtcmuDfcJD+VMzbNbpNYFZ2GpdZpmWy6xkhnmYrKjk3mub7vNlvotDvqRi6VZ7iJZNpYA7K3f0nicuXskIp9xSeVLFducI5YXTGX0Y9lrm8zN2KmM1XXrGXTjbvLYiVjfd8y4fcTPMu1Lutf6+1MpRbXBrPmuvKhmegET1flOjUFaH5W1R8OXAxPudjcV66ysj3cof6oZDFfYKQAjgVm4B1x0NzJ9LYZoT/k/Sop1c1GRrZ8b7jTncMiSdOZTnVetcbvL+0/a9dZ6VgCQ1Muylz/UE3LCmI8vVN5mRgfXqTJMjPmUm8Gb8sBYZurbcvkbvOj0mtV5g+miaslDS0dm6lw7LjfMwNh12bVIoW51HHS8XG563sPrPnhsD3gNzY2rIvFAkXRUVhNy5jOKaFHsPWAHID7ILYo7GIbNkrRwpaSAWwhx7+O7Y4Lo2EbE8Xj8BRsOZpjelZsGe3zlvq8ZefC1tcH7oE905m5w0IF34sJoqkZfjrPza9lWSFA5dpCkc0L+19+m2VJtrRDZHZu9kbU3EquFXyV/6rnpOKL46viUbGpLnUTACMoD6Ss40FGoedBDAc8iCE/gwcx9TBWsQmcruigqYKfiisIOoAXpcx3yNo6lcXt4ndVlg/OIG9LbUw6L1d6qTOZXmmLcO24noNMNxc26O+nYCwfEntf1RRqBzZhHFX1Boqvrroq/GMLQWiI7wzXKk8MYip3rQ56s9C3eaQOINYkLzJfqsY1tckC9ygFcpXKMrnr5ilD7nSXXuvEzGxHHYp61OEwYEBAgNxXt8N6hq6PHkV2k3oea3yNnaWJcuO0udSsqSs5V+m1LpIy0XZtzXVZ6rXxgSw2dba3SLaWYG1yDS/IwbVr8q6NHXK9XdrsNYiSMk+2QSo35qJvyJcGSqfog0FkatrHduqtOgAonc0GWDnC8kfAUFK0Ph2PcuSnISZB9cWA02CEPMRXA/ZG1OCkpU38lcz+o5UscBBCRriov15uJdPfZCVvYvmKFnGIAwJaH9rxpqDYD+kDEZ0+wpvnL2H+RpbwPqAHzHWxC+pmt3YgpqttUtYXEcBcub4GYOjKz8oDmC8W4oXEgpKuWIS9LuppevLgddTfPDBGA0AoRYLjEJEQnUt1sCcyX7pZvr9PeF3q00x0lD0c7rmBY+HJRcia+N4WDIbGiPrkf2884g0Rhi/qDf8oqPbGjcrvBjbAh6CvUXwK7jtnPQX6SEYr9a2o5zZOPE57d5LXCE+lm2eqFuU4riZ9IWX+1rsxtR0t2BiO9o9Sp3/dfDIWg5DpOTXxKKvCRGqnbEhQ6OiHCTVHD1H+UEm5slQxPJFZLNPqeHq267moQbKBQC9sCFuZavD18/W1vaRy5Z+vjWf3al6xLLHhd7rSefLT0EY2Y/Q5ExkGVIRsSLMzjKEQpEsbwgbOM/FAegd+nTTQF2vnuNepD43fKuxP91JbE8hIi713Cr0rtxc7HdJ1MYbf3syx2i6fFoB08mncFIfT6V5WfDS/dvLYzq9r8o+eT2OBAoEYEUiQUAgAcZcoorf7PjW9Nv12O0I9Io2XUEM/mFxdXlw3kn8RVfAgcJnkZr1rx90X1Ykq5NvPYbGIm9m1EoqeELxccsB4b3M0cC5PB9SC8zGSg4HnwL+7XhDMW3rxzmzA4aENeGurL0LY2+rjI+f3TxUa+HJKw/vPenCPKqdKC4Xdjuj5pGVgs+5R84nPpnmkTns2PeckJODgHnGMrAB2czkxkBXsFuP4z6ZDD9upNEl+Fk+aB59ys0nNnVdy98q23Z3c7hwZG4dd3wzk2efL2JpjkTekwLijwCDgHB0XYIJwV4ABQuMK8MBJar0wRtffsPeWD+c9opysvwgPU/MM+uu/UnHz95UxfFZFYd9xM+ldHq2q/O517f1iWcq5LNQJadxZ9+uM9HZ+1NeREA3pCBlBR7D/Ut5vqiN7TeCkKwkHn76cLggvkH2xsJs0Ef7c7AscINQZnpS8tSgEA0BwJwqZGH48CoH+Ez9MxLhRCPs8ZOcJQgAEvaQTsABCATiBZkcAmrOip9KSsO7LI4zZlQpESDGzpxH8bCR9e4dbIes+LBYncJTTXqYEx2Xo0Eb1TIkS6b+H1GxcnyyVuJco9TOuEVn4tt5VOs6O0b2OGO4rk4ABwYTBEPHq+3kswESciQWmuP9jirr5/q9V8Pt/AQ==</diagram></mxfile>
|
|
@ -12,22 +12,37 @@ Setup and integration
|
||||||
What you will need
|
What you will need
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
If you'd like to host your own version of converse.js or you would like to
|
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
|
integrate it into your website, then you'll need to do some further setup work.
|
||||||
more server components.
|
|
||||||
|
|
||||||
For example, if you want to allow chat accounts under your own domain (for
|
For example, if you want to allow chat accounts under your own domain (i.e.
|
||||||
example, the same domain as your website), then you will need to set up your
|
the same domain as your website), then you will need to set up your
|
||||||
own :ref:`XMPP server`.
|
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
|
Besides an XMPP server, you'll also need a way for Converse.js (which uses HTTP
|
||||||
communicate with XMPP servers (which use XMPP).
|
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`:
|
.. _`XMPP server`:
|
||||||
|
|
||||||
|
@ -36,14 +51,13 @@ An XMPP server
|
||||||
|
|
||||||
*Converse.js* implements `XMPP <http://xmpp.org/about-xmpp/>`_ as its
|
*Converse.js* implements `XMPP <http://xmpp.org/about-xmpp/>`_ as its
|
||||||
messaging protocol, and therefore needs to connect to an XMPP/Jabber
|
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
|
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.
|
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
|
You can find a list of public XMPP servers/providers on `xmpp.net <https://list.jabber.at>`_
|
||||||
servers that you can set up yourself on `xmpp.org <http://xmpp.org/xmpp-software/servers/>`_.
|
and a list of servers that you can set up yourself on `xmpp.org <http://xmpp.org/xmpp-software/servers/>`_.
|
||||||
|
|
||||||
|
|
||||||
.. _`BOSH connection manager`:
|
.. _`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>`_
|
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
|
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
|
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.
|
server, we need a proxy which acts as a bridge between these two protocols.
|
||||||
|
|
Loading…
Reference in New Issue
Block a user