Add multibox tutorial based on Nathans initial exploration

README.md

@@ -15,6 +15,7 @@ vmdb2 --rootfs-tarball=my_image.tar.gz --output my_image.img --log my_image.log
 ## Advanced Documentation
 
 * [Creating an upgrade content pack for the Butter Box](./docs/upgrade_pack.md)
+* [Set up DeltaChat messaging between multiple boxes](./docs/multibox.md)
 
 ## Copyright and Licence
 

docs/multibox.md

@@ -0,0 +1,53 @@
+## 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:
+
+```angular2html
+
+        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.