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

.. _attachments:

===========
Attachments
===========

.. note::

  Attachments from XMPP to Matrix require no special configuration.

For matridge to bridge attachments from Matrix to XMPP, you have two options:

- **HTTP Upload**: matridge will use your XMPP server's upload component (:xep:`0363`).
- **No upload**: matridge will copy attachments to a path it can write to. You then need to serve these files from via an HTTP server (eg nginx,
  prosody's `http_files <https://prosody.im/doc/modules/mod_http_files>`_, etc.).

.. _upload:

HTTP Upload
===========

matridge can use the HTTP Upload component (:xep:`0363`) of your XMPP server,
if you configure it with ``upload-service=upload.example.org`` (see :ref:`generic-config`).
In this setting, matridge will upload files just like any normal user of your server.

Example 1: prosody's mod_http_file_share
----------------------------------------

In matridge's :ref:`configuration file <config-file>`, use ``upload-service=upload.example.org``

.. code-block:: lua

  modules_enabled = {
    -- make sure http_file_share is listed here
    "http_file_share";
  }

  Component "upload.example.org" "http_file_share"
    -- allow matridge to use the upload component
    http_file_share_access = { "matrix.example.org" }

More info: `mod_http_file_share <https://prosody.im/doc/modules/mod_http_file_share>`_.

Example 2: ejabberd mod_http_upload
-----------------------------------

In matridge's :ref:`configuration file <config-file>`, use ``upload-service=example.org``

The subdomain's FQDN (example.org) should be listed under the top level 'hosts'.

.. code-block:: yaml

    hosts:
      - "example.org"

    acl:
      slidge_acl:
        server:
          - "matrix.example.org"

    listen:
      -
        port: 5443
        module: ejabberd_http
        tls: true
        request_handlers:
          /upload: mod_http_upload

    modules:
      mod_http_upload:
        # Any path that ejabberd has read and write access to
        docroot: /ejabberd/upload
        put_url: "https://@HOST@:5443/upload"
        access:
          - allow: local
          - allow: slidge_acl


To get more information about component configuration, see `ejabberd's docs
<https://docs.ejabberd.im/admin/configuration/modules/#mod-http-upload>`_.

.. _no-upload:

No upload
=========

You need to set up ``no-upload-path`` to point to a directory, and ``no-upload-url-prefix`` to an URL prefix pointing to files in that directory (see :ref:`generic-config` for more detail).
Example: ``no-upload-path=/var/www/matridge-attachments/`` and ``no-upload-url-prefix=https://example.org/matridge/`` means that ``/var/www/matridge-attachments/some-image.jpg`` is accessible at ``https://example.org/matridge/some-image.jpg``

Make sure that ``no-upload-path`` is writeable by matridge and readable by
your HTTP server. You may use ``no-upload-file-read-others=true`` to do that easily,
but you might want to restrict which users can read this directory.

.. warning::

  matridge will not take care of removing old files, so you should set up a cronjob,
  a systemd timer, or something similar, to regularly delete files, eg.
  ``find . -mtime +7 -delete && find . -depth -type d -empty -delete``
  to clean up files older than a week.

For the following examples, in matridge's config,
you would have ``no-upload-path=/var/lib/matridge/attachments``.

Example 1: prosody's http_files
-------------------------------

Here, ``no-upload-url-prefix`` would be ``https://example.org:5281/files/``,
as per the `mod_http_files documentation <https://prosody.im/doc/modules/mod_http_files>`_.

.. code-block:: lua

    modules_enabled = {
      -- make sure http_files is listed here
      "http_files";
    }

    -- Must be the same value as matridge's no-upload-path
    http_files_dir = "/var/lib/matridge/attachments"

.. _nginx-no-upload:

Example 2: nginx
----------------

Here, ``no-upload-url-prefix`` would be ``https://example.org/matridge/``.

.. code-block:: nginx

    server {
      listen 80;
      server_name example.org;
      root /var/www/html;  # if you already have nginx serving files…

      # the section below is for matridge
      location /matridge {
        #  Must be the same value as matridge's no-upload-path
        alias /var/lib/matridge/attachments/;
      }
    }

See the `nginx docs <https://docs.nginx.com/nginx/admin-guide/web-server/serving-static-content/>`_ for more info.

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

To make your matridge install top notch, set up its :ref:`privileges <privileges>`.
