ejabberd - Modern XMPP Messaging Server
========================================

A modern, production-ready XMPP instant messaging server combining
`ejabberd`_ with `Converse.js`_ web client. Supports end-to-end encryption
(OMEMO), message archiving (MAM), file sharing via HTTP Upload, multi-user
chat rooms, and federation with other XMPP servers. Works with any XMPP
client (Conversations, Dino, Gajim, Monal, etc.) and includes a built-in
web chat interface accessible from any browser.

.. _ejabberd: https://www.ejabberd.im
.. _Converse.js: https://conversejs.org

This appliance includes all the standard features in `TurnKey Core`_,
and on top of that:

- **ejabberd** (XMPP/MQTT/SIP server) installed from official ProcessOne
  repository for Debian Bookworm:

  - Modern YAML configuration with secure defaults.
  - TLS enforced on all client and server connections.
  - WebSocket support for browser-based clients.
  - `mod_mam`_ (Message Archive Management - XEP-0313): server-side
    message history with configurable retention.
  - `mod_http_upload`_ (XEP-0363): file sharing up to 20MB with
    configurable limits and automatic cleanup.
  - `mod_muc`_ (Multi-User Chat - XEP-0045): group chat rooms with
    persistent configuration.
  - `mod_conversejs`_: built-in Converse.js web client accessible at
    ``https://<domain>/conversejs`` — no separate web server needed.
  - `mod_push`_ (XEP-0357): push notifications for mobile clients.
  - `mod_vcard`_ / `mod_vcard_xupdate`_: user profiles and avatars.
  - `mod_blocking`_ (XEP-0191): user-controlled contact blocking.
  - OMEMO-ready: clients can negotiate end-to-end encryption via
    PEP/PubSub (XEP-0384).
  - In-band registration disabled by default (security); admin creates
    accounts via CLI or web admin.
  - API access via `mod_http_api`_ on localhost for automation.
  - Web administration panel on port 5280 (HTTPS).

- **Converse.js** web client served locally by ejabberd:

  - No external CDN dependencies — fully self-hosted.
  - WebSocket transport (low latency, no polling).
  - OMEMO end-to-end encryption support.
  - Multi-user chat, file sharing, emoji, message corrections.
  - Responsive design for mobile and desktop browsers.

- **PostgreSQL** database backend for production-grade storage:

  - Message archive (MAM) stored in PostgreSQL.
  - Scalable and reliable for thousands of users.

- **Let's Encrypt** SSL/TLS certificates via confconsole.
- **Postfix** MTA (bound to localhost) for email notifications.
- **Webmin** module for system administration.

Custom ejabberd initialization script for first-boot configuration::

    /usr/lib/inithooks/bin/ejabberd.sh

    # Interactive prompts for:
    #   - XMPP domain (e.g., chat.example.com)
    #   - Admin password
    #   - Admin user will be: admin@<XMPP_DOMAIN>

XMPP DNS records (replace example.com with your domain)::

    _xmpp-client._tcp.example.com.  3600 IN SRV 0 5 5222 chat.example.com.
    _xmpp-server._tcp.example.com.  3600 IN SRV 0 5 5269 chat.example.com.
    _xmpps-client._tcp.example.com. 3600 IN SRV 0 5 5223 chat.example.com.
    _xmpp-client._tcp.example.com.  3600 IN TXT "websocket=wss://chat.example.com/websocket"

Recommended XMPP clients:

- `Conversations`_ (Android) — modern, OMEMO-capable
- `Monal`_ (iOS/macOS) — native Apple platform client
- `Dino`_ (Linux) — clean GTK-based desktop client
- `Gajim`_ (Windows/Linux) — full-featured desktop client
- **Converse.js** (built-in) — web browser, no install needed

.. _TurnKey Core: https://www.turnkeylinux.org/core
.. _Conversations: https://conversations.im
.. _Monal: https://monal-im.org
.. _Dino: https://dino.im
.. _Gajim: https://gajim.org
.. _mod_mam: https://docs.ejabberd.im/admin/configuration/modules/#mod-mam
.. _mod_http_upload: https://docs.ejabberd.im/admin/configuration/modules/#mod-http-upload
.. _mod_muc: https://docs.ejabberd.im/admin/configuration/modules/#mod-muc
.. _mod_conversejs: https://docs.ejabberd.im/admin/configuration/modules/#mod-conversejs
.. _mod_push: https://docs.ejabberd.im/admin/configuration/modules/#mod-push
.. _mod_vcard: https://docs.ejabberd.im/admin/configuration/modules/#mod-vcard
.. _mod_vcard_xupdate: https://docs.ejabberd.im/admin/configuration/modules/#mod-vcard-xupdate
.. _mod_blocking: https://docs.ejabberd.im/admin/configuration/modules/#mod-blocking
.. _mod_http_api: https://docs.ejabberd.im/admin/configuration/modules/#mod-http-api

Credentials *(passwords set at first boot)*
--------------------------------------------

- Webmin, Webshell, SSH: username **root**
- ejabberd:

  - Admin interface: **admin@<XMPP_DOMAIN>** (port 5280)
  - Web chat (Converse.js): ``https://<XMPP_DOMAIN>/conversejs``

- PostgreSQL: database **ejabberd**, user **ejabberd**

Contributed by `PopSolutions Cooperative <https://pop.coop>`_ —
digital sovereignty through open-source infrastructure.