From 51aa549048e855a9053a058b07b236b13dd4c3a1 Mon Sep 17 00:00:00 2001
From: Benjamin Dweck <bjdweck@gmail.com>
Date: Fri, 23 Oct 2020 11:19:32 +0200
Subject: [PATCH] Added README.md

---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..33727b1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,73 @@
+# TORch Subscriber Docker Compose
+
+This is a [Docker Compose](https://docs.docker.com/compose/) project for assembling a service to receive TORch notifications from remote clients and store them for access via RESTful interface.
+
+It is composed of the following micro-services:
+* Tor proxy - for receving notifications from remote TORch clients via Tor
+* Broker - for managing publications and subscriptions
+* Torchsub - for receiving notifications, maintaining a database of the latest connection info for each remote note and serving them via HTTP
+
+## Running
+
+1. Create an `.env` file based on [`.env.example`](.env.example)
+
+    * CONFIG_DIR: points to the local configuration directory for the broker and torchsub micro-services
+
+    * BROKER_MQTT_PORT: must match the port that you configured mosquitto to listen for MQTT on
+    
+    * BROKER_MQTTS_PORT: must match the port that you configured mosquitto to listen for MQTTS on
+
+    * HTTP_PORT: the port that you would like Torchsub to listen on for incoming HTTP-REST requests for client connection info
+
+2. Create the local configuration directory pointed to by `.env`
+
+    1. Create [Mosquitto](https://mosquitto.org/man/mosquitto-conf-5.html) configuration files
+
+        * Create a `mosquitto.conf` based on the [example](example-config/mosquitto.conf)
+
+        * Add applicable `ca.crt`, key and/or broker certificate files as applicable for the mosquitto configuration
+
+    2. Create a `torch-sub.conf` per the [torch-subscriber-simple](https://git.rudefox.io/bj/torch-subscriber-simple) project
+
+        * Add applicable `ca.crt`, key and/or broker certificate files as applicable for the `torch-sub.conf` configuration
+
+3. Run `docker-compose up -d` from the project directory to launch the services
+
+4. Get the Tor onion hostname of your newly launched TORch node monitor
+
+```bash
+$ docker-compose exec tor svc-hostname
+*****
+* Service Onion Hostname: 24xb3hb2pajid44ugroua2ndvpipvmuw6pfjrivlbupxhpwbugfhdeqd.onion
+*****
+```
+
+5. Configure any remote [TORch agent](https://git.rudefox.io/bj/torch-agent) instances with the above onion hostname by editing their `torch.conf` files
+
+    * Set `BrokerHost` to the Tor onion hostname
+
+    * Set `BrokerPort` to the Mosquitto MQTT broker port you used above (ex. `1883`)
+
+    * You should set `RequiredCertificate` to `false` because torch-agent won't be able to match the broker's certificate to the Tor onion hostname
+
+    * Be sure to match the `Topic` with the pattern you told Torchsub to subscribe to when you configured Torchsub using `torch-sub.conf` above
+
+```bash
+# Example TORch Agent torch.conf configuration
+
+[tor]
+ControllerPort = 9051
+
+[ssh]
+Port = 22
+
+[mqtt]
+BrokerHost = 7v4jfonpcvvv4cy32po3uwqr56hvjag6ljpauennshecmzv4deq27lyd.onion 
+BrokerPort = 1883
+ClientID = vagrant
+Topic = torch/vagrant/wake
+RequireCertificate = false
+CaFile = ca.crt
+CertFile = vagrant.crt
+KeyFile = vagrant.key
+```