==========
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, run the following commands:
1. ``git clone git@github.com:conversejs/converse.js.git`` to clone the repo.
2. ``cd converse.js && npm install`` to install dependencies
3. ``npm run build`` to build distribution files to the ``./dist`` folder
4. ``npm run serve`` to start a local server at port ``8080``.
5. You can now access Converse at http://localhost:8080/dev.html in your browser.
See the :ref:`creating_builds` section for detailed build instructions and customization options.
.. tip::
You can run ``npm run watch`` to automatically rebuild the dist files whenever a source file changes.
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