EDDN/docs/Running-this-software.md

These instructions are based on getting the software up and running from scratch on a Debian Buster (10.9, stable as of 2021-05-16) system.

Base Debian Install

A simple Debian install was performed in a VirtualBox VM to ensure no confounding factors. Only the bare minimum was installed, and then the following packages also installed:

apt install screen sudo git

useradd -c 'EDDN Gateway' -m -s /bin/bash eddn

Further installation

As 'root'

Some additional Debian packages and python modules are required:

apt install python-pip

In the 'eddn' account

mkdir -p ~/eddn/dev
cd ~/eddn/dev
git clone https://github.com/EDCD/EDDN.git
pip install -r requirements.txt  # NB: Needs merging from ...

Concepts

There are three components to this application.

1. Gateway - this is where senders connect to upload messages. It performs schema validation and then passes the messages on to both the Monitor and the Relay (they connect and perform zeromq subscription).

2. Monitor - this gathers statistics about the messages, such as the sending software name and version.

3. Relay - this is where listeners connect in order to be sent messages that have passed the schema and duplicate checks.

Configuration

Application configuration is in the file src/eddn/conf/Settings.py.

1. You will need to obtain a TLS certificate from, e.g. LetsEncrypt. The application will need access to this and its private key file.

   CERT_FILE = '/etc/letsencrypt/live/eddn.edcd.io/fullchain.pem'
   KEY_FILE  = '/etc/letsencrypt/live/eddn.edcd.io/privkey.pem'
   

2. Network configuration

3. RELAY_HTTP_BIND_ADDRESS and RELAY_HTTP_PORT define the IP and port on which the application listens for new messages from the Gateway.

4. RELAY_RECEIVER_BINDINGS defines where the Relay connects in order to subscribe to messages from the Gateway. Should match GATEWAY_SENDER_BINDINGS.

5. RELAY_SENDER_BINDINGS defines the address the application listens on for connections from listeners such as eddb.io.

6. RELAY_DUPLICATE_MAX_MINUTES how many minutes to keep messages hashes cached for so as to detect, and not Relay out, duplicate messages.

7. GATEWAY_HTTP_BIND_ADDRESS and ``GATEWAY_HTTP_PORT` define where the Gateway listens to for incoming messages from senders. Might be forwarded from nginx or other reverse proxy.

8. GATEWAY_SENDER_BINDINGS is where the Gateway listens for connections from the Relay and Monitor in order to send them messages that passed schema checks.

9. GATEWAY_JSON_SCHEMAS defines the schemas used for validation. Note that these are full public URLs which are served by ...

10. GATEWAY_OUTDATED_SCHEMAS any past schema that is no longer valid.

11. MONITOR_HTTP_BIND_ADDRESS and MONITOR_HTTP_PORT define where the Monitor listens for web connections to, e.g. the statistics page.

12. MONITOR_RECEIVER_BINDINGS defines where the Monitor connects in order to subscribe to messages from the Gateway. Should match GATEWAY_SENDER_BINDINGS.

13. MONITOR_DB - defines the necessary information for the application to connect to a mysql/mariadb database for storing stats.

14. MONITOR_UA appears to be unused.

Any of these settings can be overridden by a separate config file that you then pass to the application scripts, e.g.:

python Gateway.py --config some/other/configfile.json

this way you can utilise such a file to override settings for certificate files and database credentials without worrying about the basic setup. Think of src/eddn/conf/Settings as the defaults.

Running

You have two choices for how to run the application components:

1. You can choose to run this application directly from the source using the provided script in contrib/run-from-source.sh.

2. Or you can utilise the setup.py file to build and install the application files, but this requires write permissions under /usr/local.

If you go with this option then there are also SysV style init.d scripts in contrib/init.d/ for running the components.

Accessing the Monitor

There is an EDDN Status web page usually provided at https://eddn.edcd.io/ . This is enabled by the Monitor component through the combination of the contrib/monitor/ files and API endpoints provided by the Monitor process itself.