Grin Relay Server Installation Guide

RECENT CHANGES:

• (22 Jul 2019) Creation for Grin Relay v1.0.x

1. Docker Installation

Grin Relay use RabbitMQ, so before install that, the Docker service is needed. Please refer to the good tutorials of digitalocean about Docker installation:

• In Ubuntu 18.04
• In Debian 9

2. RabbitMQ

Grin Relay use the RabbitMQ Stomp, so we need install the RabbitMQ docker.

$ docker pull rabbitmq:3.7.15-management

$ docker run -d --hostname change-to-your-server-name --name rabbitmq  -p 3418:3418 -p 3419:3419 -p 4369:4369 -p 8080:8080 -p 25672:25672 -e RABBITMQ_DEFAULT_USER=admin -e RABBITMQ_DEFAULT_PASS=admin -e RABBITMQ_LOGS=/var/log/rabbitmq/rabbitmq.log -e RABBITMQ_SASL_LOGS=/var/log/rabbitmq/rabbitmq_sasl.log  -e RABBITMQ_USE_LONGNAME=true rabbitmq:3.7.15-management

And login to your container to enable the rabbitmq_stomp plugin:

$ docker exec -it rabbitmq /bin/bash

# rabbitmq-plugins enable rabbitmq_stomp

Modify the stomp port configuration in /etc/rabbitmq/rabbitmq.conf:

stomp.listeners.tcp.1 = 127.0.0.1:61613

Remember to restart it after plugin enabled for the 1st time:

$ docker restart rabbitmq

3. Run grinrelay in the Docker

Before start it, set the following environment variables. Propose to create a script to hold these (for example, a file named as setenv.sh with the following contents):

#!/bin/bash
export BROKER_URI="127.0.0.1:61613"
export BROKER_USERNAME="admin"
export BROKER_PASSWORD="admin"
export GRINRELAY_DOMAIN="your-server-domain-name"
export GRINRELAY_PORT=3418
export BIND_ADDRESS="0.0.0.0:3418"
export GRINRELAY_PROTOCOL_UNSECURE=true
#export CERT="/etc/grinrelay/tls/server_certificate.pem"
#export KEY="/etc/grinrelay/tls/server_key.pem"

If want to use the wss service for security, remember to change the last 3 lines as:

#export GRINRELAY_PROTOCOL_UNSECURE=true
export CERT="/etc/grinrelay/tls/server_certificate.pem"
export KEY="/etc/grinrelay/tls/server_key.pem"

And the TLS certificate files need be there for wss.

Then, finally, you can start the grinrelay service by:

RUST_LOG="debug" ./grinrelay

You should see sth like these:

hello, world! let's serve for a much easier transaction :-)
Broker URI: 127.0.0.1:61613
Bind address: 0.0.0.0:3418
Listening for new connections on 0.0.0.0:3418.
broker handler started
...
established broker session
...

4. Grin Relay Service Ports

As the default, we use 3418 and 3419 ports for Grin Relay server. The port 3418 is used for ws/wss, and the port 3419 is used for multiple servers environment as the server selection service.

Remember to open these two ports in the firewall.

Note: For server clustering, the port 4369 and 25672 also needed to be open. But the sole server, it's not needed.