Added README.md

This commit is contained in:
B.J. Dweck 2020-10-23 11:19:32 +02:00
parent 75a2512438
commit 51aa549048

73
README.md Normal file
View File

@ -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
```