Skip to content

Deploying Hub20

There are a number of different methods to setup a Hub20 instance, but they all start with the same codebase and they all will require the same set of services. We will list them from easiest (most automated) to more complicated (manual setup), but the important thing to know is that in all of them the machine needs to be secured and the data residing on it can only be accessed by its operator/administrator.

These instructions assume that you are going to be running Hub20 on the internet and plan to make it available for more people beyond the operator, so you'll likely need to have a domain name to address the main application server.

DappNode

Become a sponsor to support Hub20 development

This feature is still not released or needs further improvements. If you'd like to help us to develop this, please consider becoming a sponsor. Sponsors get direct access to the developers in monthly "office-hours", priority support and discounts for work on customization.

DAppNode is an Operating System that is focused exclusively on running pre-packaged dapps and services for the distributed web. If you have a computer running dappnode at home, follow these simple steps:

  1. Ensure that are running at least one ethereum node already that is connected to the network that you want to use (mainnet or test). In case of a test network, it is highly recommended to use Göerli, as this is the network used by both Raiden and Hub20's development.
  2. Locate the Hub20 package from the package store and click "Install"
  3. You will be prompted for Raiden's private key and the method used to generate ethereum wallet, as described in the previous section of this tutorial. You will also will have to choose what network you will be using.
  4. The setup screen will also prompt for the username and password to use for the main account (i.e, the Operator). Use a strong password.
  5. If everything is working correctly, you should be able to see some messages on "logs" tab from your package.

In the specific case of the DAppNode, you will be connecting to the Hub20 through the VPN, and it should be available at hub20.dappnode.

Docker

We provide docker images if you are interested in running the application. A recommended way to run the application is to use docker-compose. You can find the code repository where we provide code for different deployment methods.

Ansible

Ansible is a tool for automated configuration management and application deployment. We provide a Hub20 Ansible Role which can automate the install of the Hub20 on any Debian-based Linux distro.

The following playbook should provide all you need, aside from the ethereum node:

- hosts: redis_servers
  gather_facts: true
  gather_subset: network
  roles:
    - role: geerlingguy.redis

- hosts: database_servers
  gather_facts: true
  gather_subset: network
  roles:
    - role: anxs.postgresql

- hosts: hub20
  tasks:
    - name: install git
      become: true
      apt:
        state: present
        name:
          - git
  roles:
    - role: geerlinguy.nginx
    - role: geerlinguy.certbot
    - role: mushroomlabs.hub20

Manual Deployment

Help with instructions for more platforms

The following instructions assume a Debian-based operating system that will be running all of the services (web application, database, redis, ethereum node) in one machine.For bigger deployments, it is advised to split these services into different hardware (or virtual servers)

If you'd like to contribute with more details to set up in different distribution, OS or setup, please don't hesitate to write it up and submit a PR.

For all the instructions below, it is assumed that you are running under an user account with privileges to make changes in the operating systems, i.e, you are either running as root or you can execute commands with sudo.

Install PostgreSQL

PostgreSQL is likely the most powerful free/open source database server which is used to power countless applications online. It is needed to store all the data related to user accounts, transaction history, information about tokens and blockchain synchronization state, keep track of sent transfers and receive payments. To install it:

sudo apt install postgresql

sudo yum install @postgresql
sudo postgresql-setup --initdb

After install, the database server should be running.

Install Redis

Redis is a "noSQL" (non-relational) database that it is used for data caching, user session management as well as the data store to keep track of all the process that are run on the background.

sudo apt install redis-server

sudo yum install epel-release
sudo yum update
sudo yum install redis
sudo systemctl enable redis
sudo systemctl start redis

Install nginx

nginx is a high-performance web server that will proxy the requests from API clients and the actual Hub20 application.

sudo apt install nginx

sudo yum install nginx
sudo systemctl enable nginx
sudo systemctl start nginx

Obtain an SSL certificate

Your server will need to use HTTPS to serve requests for clients, and to do that we will need an SSL certificate. The easiest way to do is through Let's Encrypt certbot.

Their website has instructions to install certbot for all sort of common platforms.

(Optional) Install Ethereum node client (Geth)

Info

Similar to the dappnode above, running an ethereum node requires more powerful, dedicated hardware, with at least 16GB of RAM and 1+TB of SSD to process the ethereum blockchain.

You don't want to depend on an external service like Infura, you can install an ethereum client node. Instructions to install are available on their website.

Install system packages and dependencies

So far we installed only software that is used by Hub20, but no steps were taken to install Hub20 itself.

sudo apt install git python3-pip python3-virtualenv

Create unpriviliged user that will run the service

We are going to create an user called hub20 which will have be used to run the application.

    sudo useradd -d /srv/hub20 -s /bin/bash
    sudo mkdir -p /srv/hub20
    sudo chown hub20:hub20 /srv/hub20

Create a python virtual environment

cd /srv/hub20
sudo -u hub20 python3 -m venv /srv/hub20/.venv

Install the Hub20 package

First activate the virtual environment

sudo su hub20
source /srv/hub20/.venv/bin/activate

pip install hub20

pip install git+https://gitlab.com/mushroomlabs/hub20/hub20.git

Create the configuration file

Copy the contents of the listing below to a file and save it at /etc/hub20. Pay attention to the values that you need to change (passwords and tokens)

# These values should not change
DJANGO_SETTINGS_MODULE=hub20.api.settings
HUB20_DATA_FOLDER=/var/hub20

###############################################################################
# Redis configuration.
# Change them accordngly if you are not running them all on the same host

HUB20_BROKER_URL=redis://localhost:6379/0
HUB20_CACHE_BACKEND=django_redis.cache.RedisCache
HUB20_CACHE_LOCATION=redis://localhost:6379/1
HUB20_CHANNEL_LAYER_HOST=localhost

###############################################################################
# Database configuration
# Change them accordngly if you are not running them all on the same host

HUB20_DATABASE_HOST=localhost
HUB20_DATABASE_PORT=5432
HUB20_DATABASE_NAME=hub20
HUB20_DATABASE_USER=hub20

###############################################################################
# This two values should be secured, long passwords
HUB20_DATABASE_PASSWORD=<long secret as database password>
HUB20_SECRET_KEY=<long secret string used by web application>


###############################################################################
# Ethereum tokens
# This is a comma-separated list of token addresses that you want to have listed by the hub and that will be accepted by merchants in the payment gateway.
# To indicate Ether use the special case address of 0x0000000000000000000000000000000000000000
# DAI = 0x6b175474e89094c44da98b954eedeac495271d0f
# RDN = 0x255aa6df07540cb5d3d297f0d0d4d84cb52bc8e6

HUB20_TRACKED_TOKENS=0x0000000000000000000000000000000000000000,0x6b175474e89094c44da98b954eedeac495271d0f,0x255aa6df07540cb5d3d297f0d0d4d84cb52bc8e6

###############################################################################
# Raiden configuration

RAIDEN_API_ADDRESS=http://localhost:5001
RAIDEN_ENABLE_MONITORING=true
RAIDEN_ROUTING_MODE=pfs
RAIDEN_ACCEPT_DISCLAIMER=true

# If running testnet, uncomment these values
# RAIDEN_MATRIX_SERVER=https://transport.demo001.env.raiden.network
# RAIDEN_PATHFINDING_SERVICE_ADDRESS=https://pfs.demo001.env.raiden.network

# URL of your ethereum node.
# If you installed on the same machine as the hub20 server, it will be http://localhost:8545
# if you are using infura, you will see in their dashboard a project-specific URL

WEB3_PROVIDER_URI=http://localhost:8545

Create the hub20 database

On the file above, you can see that we have define the HUB20_DATABASE_NAME and HUB20_DATABASE_USER values. These are the names of the both the database and the postgresql user that will be used. We need to create those.

set -a
source /etc/hub20
sudo -u postgres createuser $HUB20_DATABASE_USER -h $HUB20_DATABASE_HOST -p $HUB20_DATABASE_PORT -d
sudo -u postgres createdb $HUB20_DATABASE_NAME -O $HUB20_DATABASE_USER

Configure nginx site

The file below should be placed on /etc/nginx/sites-enabled folder, just make sure to replace the values in with the names are appropriate to your installation.

upstream hub20_app {
        server 127.0.0.1:5000;
    }

server {
    listen 443 ssl http2;
    server_name <your domain name>;

    ssl_certificate <path/to/certbot/fullchain.pem>;
    ssl_certificate_key <path/to/certbot/privkey.pem>;

    ssl on;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
    ssl_ecdh_curve secp384r1;
    ssl_session_cache shared:SSL:10m;
    ssl_session_tickets off;
    ssl_stapling on;
    ssl_stapling_verify on;

    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;

    location / {

        proxy_redirect off;
        proxy_buffering off;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        proxy_pass http://hub20_app;
        proxy_http_version 1.1;
    }
    location /ws {

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        proxy_pass http://hub20_app;
        proxy_http_version 1.1;
    }
    location /static/ {

        alias /srv/hub20/static/;
        autoindex off;

    }
}

Create and define systemd services

Due to the amount of systems that are communicating with each other, Hub20 needs to run several separate processes.

  • The Web server that serves the REST API
  • Celery Worker to run background tasks - e.g, any blockchain transaction or payment sent to Raiden
  • Celery Beat to run periodic maintenance tasks, such as clearing of unused sessions or checks for received payments.
  • Managed execution of the Raiden node
  • Raiden Sync to periodically check the status of raiden channels and payments

To keep these processes running and ensuring that they are restarted in case of failures, we will use systemd as our service manager, the default for most major distributions. Each of the files listed below should be placed on /etc/systemd/system

[Unit]
Description=Hub20 Web API
After=syslog.target

[Service]
EnvironmentFile=/etc/hub20
User=hub20
Group=hub20
ExecStartPre=/srv/hub20/.venv/bin/django-admin migrate
ExecStartPre=/srv/hub20/.venv/bin/django-admin collectstatic --noinput
ExecStart=/srv/hub20/.venv/bin/uvicorn hub20.api.asgi:application --env-file /etc/hub20 --port 5000 --host 127.0.0.1
Restart=always
KillSignal=SIGQUIT
Type=simple
StandardError=syslog
NotifyAccess=all

[Install]
WantedBy=multi-user.target

[Unit]
Description=Hub20 Celery Worker
After=syslog.target

[Service]
EnvironmentFile=/etc/hub20
WorkingDirectory=/srv/hub20/.venv
User=hub20
Group=hub20
ExecStart=/srv/hub20/.venv/bin/celery -A hub20.api worker -l info
Restart=always
KillSignal=SIGQUIT
Type=simple
StandardError=syslog
NotifyAccess=all

[Install]
WantedBy=multi-user.target

[Unit]
Description=Hub20 Celery Beat
After=syslog.target

[Service]
EnvironmentFile=/etc/hub20
User=hub20
Group=hub20
ExecStart=/srv/hub20/.venv/bin/celery -A hub20.api beat -l info -s /srv/hub20/celery/celerybeat-schedule.db --pidfile=/srv/hub20/celery/celerybeat.pid
Restart=always
KillSignal=SIGQUIT
Type=simple
StandardError=syslog
NotifyAccess=all

[Install]
WantedBy=multi-user.target

[Unit]
Description=Hub20 Web3 Event Listener
After=syslog.target

[Service]
EnvironmentFile=/etc/hub20
User=hub20
Group=hub20
ExecStart=/srv/hub20/.venv/bin/django-admin run_event_listeners
Restart=always
KillSignal=SIGQUIT
Type=simple
StandardError=syslog
NotifyAccess=all

[Install]
WantedBy=multi-user.target

[Unit]
Description=Hub20 Raiden Sync
After=syslog.target

[Service]
EnvironmentFile=/etc/hub20
User=hub20
Group=hub20
ExecStart=/srv/hub20/.venv/bin/django-admin sync_raiden
Restart=always
KillSignal=SIGQUIT
Type=simple
StandardError=syslog
NotifyAccess=all

[Install]
WantedBy=multi-user.target

[Unit]
Description=Hub20 Raiden Sync
After=syslog.target

[Service]
EnvironmentFile=/etc/hub20
User=hub20
Group=hub20
ExecStart=/srv/hub20/.venv/bin/django-admin run_raiden
Restart=always
KillSignal=SIGQUIT
Type=simple
StandardError=syslog
NotifyAccess=all

[Install]
WantedBy=multi-user.target

After installing these files, you should run:

sudo systemctl enable hub20_*
sudo systemctl start hub20_*
sudo systemctl reload nginx

Voila, your services should be up and running. You can check the logs messages by executing:

journalctl -u hub20_* -f

Bear in mind that this will get the output of all services simultaneously and it might be difficult to follow it all.