Adding Messaging to a Mastodon Server

This wiki should eventually become the definitive setup guide to integrating XMPP-based messaging services for your Mastodon users. The repository will contain example config files where possible and we'll link to those here as need.

Assumptions

Setting up your Mastodon server is out of scope for this guide, we're going to take it as read that you've got that part down, and you're running a reasonably current version. Later enhancements that are largely theoretical at the time of writing may require modifications to the Mastodon code, or use of a particular fork.

The reference implementation (Chinwag Social) code is available for inspection here. If a specific change is required for a feature, we'll mention it.

Goals

Overall, the intention is for end users to have full and free access to a functional instant message service that's capable of federation and has a multitude of client applications ready to go. From the user perspective there should be no real indication that their Mastodon account and their messaging account are different things. All relevant user preferences and settings should ideally be reflected identically whether using a messaging or social application.

That said, the messaging service should be entirely optional. It should not intrude on the Mastodon experience (like showing new message notifications etc - unless explicitly invited to do so) and disabling it should leave no trace it was ever there. It may be desirable eventually to look at gateways to permit the viewing or replying to direct messages in Mastodon via IM, but this should probably not be the default.

Overall, tight integration is desirable, but respect for user preferences should be paramount and use of the service should never be a requirement.

The messaging system should always remain 100% compatable and capable of federation with any service running a standard XMPP-based service, not just Mastodon-backed systems.

Deployment

These points should all become individual wiki pages:

Install and configure ejabberd
Add https://git.chinwag.org/chinwag/ejabberd-auth-mastodon and configure database
Configure Nginx for HTTP uploads, BOSH, Websockets
Set up required SRV and TXT records for service
Install Let's Encrypt certificates for all required subdomains
Modify system firewall for XMPP service ports
Test with XMPP.net, Conversations compliance tool
Optional: Biboumi IRC gateway
Testing with internal and external users, chat rooms, video calling, etc.