..  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/install.rst.jinja
    Open a pull request for this repository instead, to benefit the documentation of all slidge-based gateways.

Installation
------------

Containers
~~~~~~~~~~

A container is built on every push to the git repository and uploaded to `the codeberg package
registry <https://codeberg.org/slidge/-/packages/container/matridge/latest>`__.

.. code:: sh

   docker run codeberg.org/slidge/matridge:latest  # works with podman too

Use the ``:latest`` tag for the latest release, ``:vX.X.X`` for release
X.X.X, and ``:main`` for the bleeding edge.


For data persistence, mount a writeable directory into ``/var/lib/slidge``. Inside the container,
matridge runs as the ``slidge`` user with UID/GID 10000/10000.

matridge must be able to :ref:`reach your XMPP server <setup-component>`, so set up networking accordingly.

Python packages
~~~~~~~~~~~~~~~

.. image:: https://badge.fury.io/py/matridge.svg
    :alt: PyPI package version
    :target: https://pypi.org/project/matridge/

matridge is available on the `python package index (PyPI) <https://pypi.org/project/matridge/>`__.

If you are not familiar with python packaging, we recommend using `pipx <https://pypa.github.io/pipx/>`__ to
set up matridge and its dependencies, isolated from the rest of your system.

.. code:: sh

   # for the latest stable release published to PyPI, if any
   pipx install matridge

   matridge --help

Bleeding edge versions are also available on `codeberg's python index <https://codeberg/slidge/-/packages/pypi/matridge>`_.

.. code:: sh

   # for the bleeding edge
   pipx install matridge \
       --pip-args='--extra-index-url https://codeberg.org/api/packages/slidge/pypi/simple/ --pre'

Distribution packages
~~~~~~~~~~~~~~~~~~~~~

matridge is available in the official repositories of a few linux distributions.

.. image:: https://repology.org/badge/vertical-allrepos/slidge-matridge.svg
    :alt: Packaging status
    :target: https://repology.org/project/slidge-matridge/versions

Unofficial debian package
~~~~~~~~~~~~~~~~~~~~~~~~~

If you are using debian you might be interested in installing the
`slidge (unofficial) debian
package <https://codeberg.org/slidge/debian>`__ which bundles matridge
along with other slidge-based XMPP gateways.

Follow the instructions in the repository `README <https://codeberg.org/slidge/debian/src/branch/main/README.md>`_. In short:

- :ref:`Configure <setup-component>` your XMPP ;
- edit ``/etc/slidge/conf.d/common.conf``;
- edit ``/etc/slidge/matrix.conf``;
- run ``sudo systemctl start slidge@matrix``;
- watch the logs with ``sudo journalctl -u slidge@matrix -f``.


.. include:: install-custom.rst
