.md

Run a byteball-relay or byteball-hub on Raspberry PI or any other GNU/Linux
============================================================================

This guide is meant to be easy to follow yet informative on the actions taken to install
and configure a byteball relay, hub or witness.

A **byteball relay** is meant to help the network by forwarding messages between users and light
wallets, to connect those who have restrictive firewalls or otherwise cant connect, a byteball-relay
is also meant to offload the hubs networking capacity.

Relay is simplest to setup and start as it almost doesnt require any configuration.

Next on the ladder is **byteball-hub** which besides forwarding messages as a realy, will also keep
them for a short time until other device/user is online. To run a hub it needs to know which domain-name
or IP address it can be reached at, and a web-server is needed in front of the hub.

A **witness** is a hub but also has a headless-wallet built in. It is doing all a relay+hub is doing, and
is also stamping transactions it sees - gathering comission/fee, and paying for some, this one is most complicated
to setup as it requires more configuration.

Byteball sofware uses *web-sockets* to communicate with each other, web-socket is over HTTP, as this
allows good connectivity and security. A **web-server is recommended** to be installed and configured to handle
the HTTP connections, upgrades to Web-Socket connections. The web-server will take the incoming connection
and pass it to the "backend" byteball software.

The # before a command means it has to be run as root user, or alternative with sudo as prefix to the command.

1. Install Node.JS and the node package manager, npm, and git
-------------------------------------------------------------
If on Debian like Ubuntu, as root, or sudo

    # apt-get install nodejs npm node-sqlite3 git logrotate

If on CentOS like RHEL, as root, or sudo

    # yum install nodejs npm node-sqlite3 git logrotate

If on ArchLinux, as root or sudo,

    # pacman -S node npm git logrotate sqlite

If on anything else, consult your distributions handbook/wiki.
To verify that you have node and npm installed these comands should succeed,
do not proceed until this is fixed. But your version number may be different.

    # which node
    /usr/bin/node

    $ node -v
    v4.2.6

    # which npm
    /usr/bin/npm

    $ npm -v
    4.1.2

Casual problems for not succeding installing nodejs npm git and logrotate, is
no internet connection when running apt-get/pacman/yum commands, or your package
repositoriy/package-managament needs some love. Try running

    # apt-get update

    and see if it succeeds, success should end with this,

    Fetched 1836 kB in 1s (1256 kB/s)
    Reading package lists... Done

2 .Setup a user account for increased security
----------------------------------------------

Not your normal user account, not root, add specific user with different name than given in this example,
As root run,

    # useradd -m servesbytesnet

Then again as root set a password with

    # passwd servesbytesnet

3. Change to user account and retrieve the byteball-relay code

If root or any other user

    su - servesbytesnet

    servesbytesnet $ id

Now you should be servesbytesnet and ready to retrieve the byteball software,
by running

    git clone https://github.com/byteball/byteball-hub.git


4. Step Install required node packages
--------------------------------------

Still as the servesbytesnet user change directory, cd, to newly cloned byteball-hub source code directory,

    $ cd ~/byteball-hub
    $ npm install


5. Step Troubleshoot any problems with above command, ask people, complain failings to package maintainers
----------------------------------------------------------------------------------------------------------


6. Step Test the application with
---------------------------------

    $ node start.js

It should spew alot of things,
which means it  runs fine, abort it with Ctrl+C, or in another terminal run

    $ killall node


7. Configure byteball-hub application
-------------------------------------

Make changes to the conf.js file with vim or nano

    $ vim conf.js

Edit the fields

    exports.port = 6611;
    //exports.myUrl = 'wss://mydomain.com/bb';
    exports.bServeAsHub = false;

The difference between a hub and relay is the exports.bServeAsHub = true or false, both a hub and relay
need a port, and a hub only needs a myUrl - which is advertised when talking with other peers on the network so they can discover you.

Test it again.


8. Configure the OS to run the application as a service with monitoring
-----------------------------------------------------------------------

run the node application as a service meaning it will restart on failure, and care for disk space by rotating logs

Simplest is to not care about systemd or openrc or initv or other operating system service things, but do the dumb 1970s style way, with cron and logrotate,
we add a "run the 'please start the byteball hub relay or witness' script every 5 monutes'", and logrotate every 30min, with
logrotate configuration saying to rotate it if size is bigger than set amount, rotate logs and so on.

    $ crontab -e

You will be dropped to editor, like Vim, or nano so you can add add these lines

    */5 * * * * ~/start_byteball_application.sh
    */30 * * * * logrotate -s ~/logrotate_byteball.status ~/logrotate_byteball.conf


Now then the contents of the script ~/start_byteball_application.sh is this
`

    #!/bin/bash

    # adjust for hub or relay or witness

    cd ~/byteball-hub

    echo "Starting at $(date) in $PWD" >> ./start.log
    ps aux | grep -q [n]ode && exit 0
    echo 'Shit happened $(date)' >> ./start.log

    [ -d ~/logs ] || mkdir -p ~/logs

    # if you run a witness use this line
    # echo 'your-private-passphrase-here-if-running-a-witness' | node start.js >> ~/logs/witness_log.txt 2>&1 &

    # if you run a hub or relay its enough to run this
    node start.js >> ~/logs/hub_log.txt 2>&1 &


The ~/logrotate_byteball.conf looks like this, and says everything matching the first line should be compressed and you can add a rotation to delete older than 15 logs,
and to copytruncate, meaning the log already being written should be truncated, its then very important that you do node start.js >> that is append and not > above in the script.

`
/home/servesbytesnet/*/logs/*_log.txt {
        notifempty
        size 512M
        missingok
        copytruncate
        start 0
        #rotate 15
        compress
}
`

9. Install and configure nginx
------------------------------

The nginx is in front of the node.js application and can help with caching/load-balancing and some small security benefit.
...


10. Harden security checkup
---------------------------

* Ensure at least simple firewall is running with these commands below, this will drop any incoming packages, except those which are
in the state related, established, those which speak tcp and want to reach port 2222 and 443, will be let through, everything else
will be politely denied.

`
cat /etc/iptables/simple_firewall.rules
*filter
:INPUT DROP [0:0]
:FORWARD DROP [0:0]
:OUTPUT ACCEPT [0:0]
-A INPUT -p icmp -j ACCEPT
-A INPUT -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
-A INPUT -i lo -j ACCEPT
-A INPUT -p tcp --dport 2222 -j ACCEPT
-A INPUT -p tcp --dport 443 -j ACCEPT
-A INPUT -p tcp -j REJECT --reject-with tcp-reset
-A INPUT -p udp -j REJECT --reject-with icmp-port-unreachable
-A INPUT -j REJECT --reject-with icmp-proto-unreachable
COMMIT
`
* Setup auto-updating of OS packages, as root crontab -e, and add, pacman --noask -Syu


11. Check back to your server from time to time
-----------------------------------------------

Good luck son