..  GENERATED FILE, DO NOT EDIT DIRECTLY

    This file is automatically generated using https://codeberg.org/slidge/legacy-module-template/
    Its source is at:
    https://codeberg.org/slidge/legacy-module-template/src/branch/main/docs/source/admin/quickstart.rst.jinja
    Open a pull request for this repository instead, to benefit the documentation of all slidge-based gateways.


.. _quickstart:

===========
Quick start
===========

.. _setup-component:

Setup an XMPP server component
==============================

matridge uses the `Jabber Component Protocol <https://xmpp.org/extensions/xep-0114.html>`_ to
connect to an XMPP server.
matridge itself needs to have a JID without a local part, such as ``matrix.example.org``.
In a typical deployment, matridge runs on the same host as the XMPP server and connects to it via ``localhost``.
This requires adequate configuration of the XMPP server, and depends on the XMPP server software you are using.

This documentation explains how to do that for
`prosody <https://prosody.im/doc/components>`_
and `ejabberd <https://docs.ejabberd.im/developer/hosts/>`_.
It might be outdated and you may want to check the official, up-to-date documentation of the XMPP server you are using.
If you know how to set up slidge with other XMPP servers, please contribute to the docs. ;-)

Prosŏdy
-------

Add a component block below the appropriate virtualhost in ``prosody.cfg.lua``

.. code-block:: lua

    Component "matrix.example.org"
      component_secret = "some-secret-string"

ejabberd
--------

.. code-block:: yaml

    listen:
      -
        ip: 127.0.0.1
        port: 5347
        module: ejabberd_service
        hosts:
          matrix.example.org:
            password: some-secret-string

Launch the daemon
=================

Start matridge with:

.. code-block:: bash

  matridge \
    --jid matrix.example.org \
    --secret some-secret-string \
    --home-dir /somewhere/writable

Next steps
==========

Next, you probably want to set up :ref:`attachments <attachments>` to support bridging files from Matrix to XMPP.
