==========
Quickstart
==========
You can use the latest version of Converse at `conversejs.org `_.
There are several ways to run Converse yourself or to add it to your website or web app:
Option 1: Host it via your XMPP Server
======================================
If you run your own XMPP server, check if it has a plugin for hosting Converse.
For example, the following XMPP servers have plugins available:
* **Openfire**: `inverse plugin `_
* **Prosody**: `mod_conversejs `_
* **ejabberd**: `mod_conversejs `_
Option 2: Self-hosting
======================
Getting the necessary files
---------------------------
You can host Converse on your own server without requiring any XMPP server.
There are three ways to get the necessary files:
A. Using the CDN (Recommended)
******************************
Converse provides a CDN (via `KeyCDN `_) for easy integration.
To use it, add these lines to your HTML page's ```` section:
.. code-block:: html
.. warning::
Always specify a version number in production to avoid breaking changes.
B. Download Pre-built Files
***************************
1. Download the latest release from the `Converse GitHub releases page `_
2. Extract the archive file
3. Include the minified files in your HTML:
.. code-block:: html
.. important::
* All the files from the ``dist`` directory need to be available and hosted on your server
* Converse will dynamically load additional files from this directory
* To use a different path, change the :ref:`assets_path` setting
C. Build from Source
********************
For custom builds and development:
1. Clone the `Converse repository `_ by running ``git clone git@github.com:conversejs/converse.js.git``
2. Run ``npm install`` to install dependencies
3. Run ``npm run build`` to build distribution files to the ``./dist`` folder
4. Run ``npm run serve -- -p 8008`` to start a local server at port ``8008``.
You can then access Converse at http://localhost:8008 in your browser.
See the :ref:`creating_builds` section for detailed build instructions and customization options.
.. tip::
If you have GNU Make installed, you can just run ``make watch``, to do all the above steps automatically.
Initializing Converse
---------------------
After building and including the necessary files, you need to initialize Converse:
.. code-block:: html
See the :ref:`configuration-settings` section for all available initialization options and the
`index.html `_ file in the repository for a complete example.
Display Modes
*************
Converse supports different display modes:
* **Full page mode** (default): Chat takes up the entire page
* **Overlay mode**: Chat appears in a corner of your page
* **Embedded mode**: Chat appears embedded inside a container element in your page
To use fullscreen mode, simply set the ``view_mode`` parameter:
.. code-block:: javascript
converse.initialize({
view_mode: 'fullscreen' // other options are `overlay` and `embedded`
});
Further reading
===============
Now that you have Converse running, you might want to:
* Explore available :ref:`features ` (some require additional setup)
* Implement :ref:`session-support` for single sign-on between your site and XMPP
* Enable :ref:`OMEMO encryption ` (requires loading `libsignal-protocol.js `_)
* Create :doc:`custom builds ` with specific features
* Customize the appearance with :doc:`theming `
* Dive into :doc:`development ` to contribute or extend Converse