This page documents what you'll need to do to be able to connect Converse.js with
This page documents what you'll need to do to be able to connect Converse with
your own XMPP server and to better integrate it into your website.
At the very least you'll need Converse.js and an :ref:`XMPP server` with
At the very least you'll need Converse and an :ref:`XMPP server` with
:ref:`websocket-section` or :ref:`BOSH-section` enabled. That's definitely
enough to simply demo Converse.js or to do development work on it.
enough to simply demo Converse or to do development work on it.
However, if you want to more fully integrate it into a website or intranet,
However, if you want to more fully integrate it into a website
then you'll likely need to set up more services and components.
The diagram below shows a fairly common setup for a website or intranet:
* Converse.js runs in the web-browser on the user's device.
* Converse runs in the web-browser on the user's device.
* It communicates with the XMPP server via BOSH or websocket which is usually
reverse-proxied by a web-server in order to overcome cross-site scripting
...
...
@@ -34,13 +34,12 @@ The diagram below shows a fairly common setup for a website or intranet:
the XMPP server is configured to use, so that users can log in with those
credentials.
* Usually (but optionally) there is a backend web application which hosts a
website in which Converse.js appears.
website in which Converse appears.
.. 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.
:alt: A diagram of a possible setup, consisting of Converse, a web server, a backend web application, an XMPP server, a user directory such as LDAP and an XMPP server.
This diagram shows the various services in a fairly common setup (image generated with `draw.io <https://draw.io>`_).
...
...
@@ -53,11 +52,11 @@ The various components
An XMPP server
==============
*Converse.js* implements `XMPP <http://xmpp.org/about-xmpp/>`_ as its
*Converse* uses `XMPP <http://xmpp.org/about-xmpp/>`_ as its
messaging protocol, and therefore needs to connect to an XMPP/Jabber
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 ``conversejs.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 <https://list.jabber.at>`_
...
...
@@ -79,7 +78,7 @@ stanzas to be sent over an HTTP connection.
HTTP connections are stateless and usually shortlived.
XMPP connections on the other hand are stateful and usually last much longer.
So to enable a web application like *Converse.js* to communicate with an XMPP
So to enable a web application like *Converse* to communicate with an XMPP
server, we need a proxy which acts as a bridge between these two protocols.
This is the job of a BOSH connection manager. BOSH (Bidirectional-streams Over
...
...
@@ -87,7 +86,7 @@ Synchronous HTTP) is a protocol for allowing XMPP communication over HTTP. The
protocol is defined in `XEP-0206: XMPP Over BOSH <http://xmpp.org/extensions/xep-0206.html>`_.
Popular XMPP servers such as `Ejabberd <http://www.ejabberd.im>`_,
prosody `(mod_bosh) <http://prosody.im/doc/setting_up_bosh>`_ and
Prosody `(mod_bosh) <http://prosody.im/doc/setting_up_bosh>`_ and
`OpenFire <http://www.igniterealtime.org/projects/openfire/>`_ all include
their own BOSH connection managers (but you usually have to enable them in the
configuration).
...
...
@@ -98,14 +97,15 @@ https://conversejs.org does), then you'll need a standalone connection manager.
For a standalone manager, see for example `Punjab <https://github.com/twonds/punjab>`_
and `node-xmpp-bosh <https://github.com/dhruvbird/node-xmpp-bosh>`_.
The demo on the `Converse.js homepage <http://conversejs.org>`_ uses a connection
The demo on the `Converse homepage <http://conversejs.org>`_ uses a connection
manager located at https://conversejs.org/http-bind.
This connection manager is available for testing purposes only, please don't
use it in production.
Refer to the :ref:`bosh-service-url` configuration setting for information on
how to configure Converse.js to connect to a BOSH URL.
how to configure Converse to connect to a BOSH URL.
.. _`websocket-section`:
...
...
@@ -122,7 +122,7 @@ HTTP. Therefore BOSH, which operates over HTTP, doesn't apply to websockets.
does the node-xmpp-bosh connection manager.
Refer to the :ref:`websocket-url` configuration setting for information on how to
configure Converse.js to connect to a websocket URL.