churn/docs/multibox.md

Multi-box Delta Chat setup

This document details the requirements and setup needed to allow exchanging messages between Delta Chat instances running on different boxes connected together over LAN. This requires a few configuration changes.

Requirements

• A way to access the boxes via console, either by using a keyboard and monitor, or by enabling the SSH setting through the admin portal and connecting via SSH.
• The boxes must be configured with different hostnames, e.g., butterbox.local and jambox.local. The hostname can only be changed at the time of the initial admin setup for a box.
• The boxes must be connected together in the same LAN, either by being plugged into the same router, or by reconfiguring one of them to be a client of the hotspot provided by the other.
• The rest of the instructions assume the router provides the boxes with IP addresses via DHCP.

MDNS Setup

• After making sure the boxes are on the same network, check they can resolve each other's local names, by running an MDNS lookup command (avahi-resolve -n -4 <name.local>) on one of the boxes for the hostname of the others. The following example shows the address of jambox.local being resolved on the console of the box named butterbox.local:

root@butterbox:~# avahi-resolve -n -4 jambox.local

jambox.local	192.168.1.2

• If the above does not work, it could be due to a variety of reasons, the most likely being that the router used to connect the boxes does not support forwarding MDNS queries. In this case, run the command ip a to find the local eth0 address for each box, and then add that into the /etc/hosts file on the other boxes. This will allow them to find each other by hostname. For example, if jambox.local had an address of 192.168.1.2, you would need to add the following line to /etc/hosts on butterbox.local:

192.168.1.2 jambox.local

• In this example, the corresponding config change would also need to be made for any other connected boxes, e.g., jambox.local's /etc/hosts file.

Nginx setup

• Edit the /etc/nginx/sites-enabled/default file to add an entry for /mxdeliv that points to localhost, port 8081, on all boxes participating in the setup:

        location /mxdeliv {
                    proxy_pass http://127.0.0.1:8081;
                   }

Testing

With the changes above, each box should be able to find the other boxes for mail delivery, with incoming mail routed by nginx to the madmail service. To test, create Delta Chat accounts on each box, and send test messages between them.