FRIDAY 5th Nov 2021
Wasp v0.2.2 released

SATURDAY 13th Nov 2021. Iota Discord, SmartContracts channel. Evaldas [IF]: We won’t support versions of Goshimmer higher than in the 0.7.7, we’ve frozen it. Wasp is moving to the Chrysalis platform.

MONDAY 8th Nov 2021
SWARM v1.0.0 released

Installing an Iota Wasp node on a Netcup virtual server (Ubuntu 20.04) using SWARM

last change to this doc - 13 Nov 2021

NB TangleDust.com is not an official Iota site but this guide includes many Iota official links. Please note also that Wasp is regularly being updated so these instructions may be out of date. See the official Iota Wiki for the latest and best information. If you want to give feedback then the author of these notes is @dumdave on the Iota Discord server.

If you wish to contribute to the preparation and improvement of this guide and others coming on the TangleDust.com website then please demonstrate the efficiency of the Iota network by donating a few Miota to this Iota address, but remember that most credit should go to the clever creators of SWARM, and of Wasp itself.

iota1qp2fgd7nn00x09lnru7lzya3a72khuqrw25yafc3ehhuz2ucykpgk8m0hum

There will soon be a separate guide on 'Wasp-CLI' to cover more on using Wasp for Smart Contracts.

Iota Wasp

Wasp is node software developed by the IOTA Foundation to run the IOTA Smart Contract Protocol (ISCP in short) on top of the IOTA Tangle (Iota network v2.0).

Iota 2.0 runs on its own development network. Everything is highly experimental and subject to change. Tokens in Iota 2.0 DevNet don't have value.

Wasp works with Iota Goshimmer, which is the main node which is connected to Iota network 2.0

If you are planning on experimenting with Iota Smart Contracts then you may find having your own Goshimmer node useful - though in the short term there are 'community' Goshimmer nodes that you can attach to instead if that is your main interest. For other nodes see also these guides.

Guide 1. Notes on installing an Iota Hornet Node with SWARM
Guide 2. Notes on installing an Iota Bee Node with SWARM
Guide 3. Notes on installing an Iota Goshimmer Node with SWARM

SWARM Script

SWARM is an interactive shell script written using 'whiptail'. This provides a user-friendly menu to perform virtually all of the necessary actions. It is produced by TangleBay. For interest, you can see their Github at the following address, though please follow the guide below for installation etc.

Please note that SWARM can install all four Iota nodes, Hornet, Bee, Goshimmer and Wasp. See above for more.

github.com/TangleBay/swarm

Support by Iota and TangleBay

If you are planning to install an Iota node then you are strongly advised to join the Iota Discord which has channels covering each and every aspect of the Iota project and hundreds of enthusiastic members who will give you advice. Tanglebay also has a Discord for more specific issues to do with SWARM - they also offer other useful services. The Iota website is also a good starting point.

www.iota.org

Netcup Virtual Server

These notes are based on an installation on a Netcup virtual server running Ubuntu 20.04, but obviously are applicable to other similar server setups. Why Netcup, located in Karlsruhe, Germany? The cost for a one year contract was Euro 72.61 (including VAT) as at Oct 2021 - about £62. Hetzner offer a similar service.

www.netcup.eu/vserver/vps.php


Netcup virtual server offering

You may find the process of ordering a little different because of their 'know your customer' procedures. So (a) place your order online. Be sure to complete all of the requested details inc. phone numbers. (b) be contacted while they check who you are. (c) receive an invoice and access to your Customer Control Panel (d) pay the invoice (e) get access to your Server Control Panel. They are quite used to dealing with English speakers so no need to brush up on your German first. All interfaces are naturally available in English!

NB The Server Control Panel is also useful later if you need to reboot the server because you cannot get access. It has a Powercycle option that does the trick! Use the Control option on the left menu.

Netcup Server Control Panel

Installing Ubuntu is trivial. Select the server, go to Media on the lefthand menu then Images on the top menu. On the main screen select the Distribution 'Ubuntu 20.04 LTS' then follow the menu options.

There are many steps needed after that to set up a secure SSH connection, but notes on that are available in many places. These notes continue on from a situation where SSH has already been setup

Uncomplicated Firewall

One thing that is worth mentioning is the need for a firewall, in this case 'ufw'. The key commands at the Terminal are in this form:

sudo apt install ufw => the installation

sudo ufw status => see which ports are allowed and disallowed

sudo ufw allow 22/tcp => or just sudo ufw allow 22 (or deny)

To run a Wasp node you need to open the following ports:

peering: 4000 tcp

nanomsg: 5550 tcp

The Iota Wiki has lots of well written information about Smart Contracts. Use this link if you want to delve into more detail.

wiki.iota.org/wasp/overview

Installing SWARM

Check with the SWARM Github site Readme for the latest information if in doubt. That currently suggests using:

curl -sL https://raw.githubusercontent.com/tanglebay/swarm/master/installer.sh | sudo bash -

After that, simply typing 'swarm' (quote marks not needed) at any time in Terminal while connected to your server should trigger the script and give you the menu below. Just use the arrow keys and Enter to navigate around. To exit a screen usually you use right arrow to get to Cancel and then press Enter.

Note that this is v0.9.9 but you can expect SWARM to be rapidly evolving. The first option on the main menu 'SWARM Menu' and then option 4 for 'Manage SWARM' allows you to update it as necessary.

SWARM Main Menu

Installing an Iota Wasp Node using SWARM

As these notes are concerned with installing an Iota Wasp node, select 5 on the front page of the SWARM Menu:

SWARM Top Menu

That gets you to this menu.

SWARM Wasp Menu

The first step is to Install Wasp, so select option 4 to access the sub-menu below.

SWARM Goshimmer Install Menu

Finally, select Option 2 to trigger the installation of Wasp. Once that is done, you should get this message.

SWARM Goshimmer Installed screen

Back at the Wasp menu shown above select option 1 'Wasp Info' and, if all is well, you will see a screen like the one below showing that Wasp is active.

SWARM Wasp Info screen

The Iota Wasp Dashboard

Although it cannot be accessed easily yet on a remote server, it is worth looking at the Iota Wasp dashboard to show why it is useful. There is usually a login screen first, so if you are at that stage then the default UN and PWD are usually 'wasp' and 'wasp' but you can change this in the SWARM menus:

Wasp dashboard 1/2

Wasp dashboard 2/2


It is also worth while looking briefly at the two other tabs that are available, even though they are blank at the moment. The first is the PEERING tab, which is where other WASP nodes will appear unless the situation only uses a single Wasp node - which is certainly possible and commonly used for developing solutions.

Wasp dashboard peering tab


The second tab is for CHAINS which form the underlying structure of an Iota Smart Contract. These are not discussed further in this guide but see the separate guide to the Wasp-CLI (Command Line Interface)

Wasp dashboard chains tab


Setting up Reverse Proxy with SWARM

If you plan to set up other Iota nodes, for example Bee or Hornet then it is best to set up their Reverse Proxy at the same time as the Wasp one. SWARM goes through a process that includes using 'letsencrypt' to set up the SSL certificate for the domain you are using, which it ideally only needs to do once if you are using a single host name as below.

For example, if the Netcup setup being used for these notes was given the host name: v2202110158313xxxxxx.ultrasrv.de and if Bee, Hornet, Goshimmer and Wasp were setup on the server they could be accessed by different ports as below.

In other words, the reverse proxy needs to use just the port number to distinguish where to redirect to. More information on this is below, but SWARM will arrange it all with no further input once you have supplied your choice of port numbers and told it the host name.

Hornet dashboard: https://v2202110158313xxxxxx.ultrasrv.de:444/dashboard

Bee dashboard: https://v2202110158313xxxxxx.ultrasrv.de:445/dashboard

Wasp dashboard: https://v2202110158313xxxxxx.ultrasrv.de:446/dashboard

Goshimmer dashboard: https://v2202110158313xxxxxx.ultrasrv.de:447/dashboard

NB Safari has been found to sometimes not display Goshimmer easily, while Chrome does.

NB If you are installing Wasp then there will be a 5th port needed for the Wasp API (e.g. 448)

SWARM Reverse Proxy

Returning to SWARM, from the home page of the menu, select Proxy Menu. Be sure to have listed a port number for each of the items that you plan to install.

SWARM Reverse Proxy

IMPORTANT. You first need to configure the port settings before you deploy the reverse proxy, so be sure to first select Option 2 as below.

SWARM Configure Proxy

That takes you to this page, where you repeat the same procedure for any item you have installed or plan to install

SWARM Configure Proxy Wasp

For example, for Wasp you have this menu page which asks you in turn for the Wasp domain and the Wasp port for the dashboard AND the API. In this case the domain is: v2202110158313xxxxxx.ultrasrv.de and the port is:446 and then 448.

SWARM Configure Proxy Wasp settings

Note that there is also a Proxy Settings option for the Landing Page - which is where SWARM can install the following. Note that it is dynamic with three options: Green=active Red=inactive Grey=not installed. Clicking on any of the images should take you to the Dashboard of the relevant node.

SWARM Landing Page

Deploying the Reverse Proxy

Now that you have entered the port settings etc, the reverse proxy can be deployed by SWARM. It uses 'nginx' for which the docs are here if you need to dig into what is happening. Further below there is more detail on the relevant files used etc but be aware that if you use SWARM it will reset any changes you make to fit the settings you entered through SWARM.

https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/

Returning to the SWARM menu, select 4 for the Proxy Installer as in the screen below.

SWARM Proxy Installer

You then have a menu to select the actual install. If all goes well then this should run and do several things. (a) Get an SSL certificate, (b) Run nginx and set up the reverse proxy by putting files into the /etc/nginx/sites-enabled folder, (c) Set up a landing page to make it easy to navigate between the nodes and to monitor their condition.

SWARM Proxy Installer page 2

Congratulations. You should now have access to the dashboard of your Wasp node. There is some more useful information below on the config.json file and the nginx reverse proxy files, but there is also one more useful area of SWARM to note.

SWARM Watchdog

Watchdogs are used to monitor if a system is running and to take appropriate action if not. SWARM implements a watchdog system. Go to the SWARM menu home page and select 1 then you should find the following screen where you select 2 to Configure SWARM.

Configure SWARM page

This page lets you decide whether to enable or disable Watchdog, and if you do enable it then to decide on the settings you'd prefer for various aspects of the installation. It is a very powerful tool so it is wise to spend a little time looking around here, particularly if you wish to make edits of some settings and do not want SWARM resetting them for you.

Configure SWARM Watchdog

This is a typical Watchdog 'info' page on SWARM v0.9.9 which shows just how much Watchdog is able to do.

Typical SWARM Watchdog info

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

End notes on Wasp Installation with SWARM

IMPORTANT. DO NOT MAKE CHANGES DIRECTLY TO THE CONFIG FILE IF USING SWARM - SWARM WILL USUALLY OVERRIDE THEM

The Wasp Config file

The config file for the installation of Wasp (config.json) is at: /var/lib/wasp. The config file looks like this (NB various random changes made to seeds, keys, passwords etc out of habit so do not rely on those). Note that the dashboard is on local port 7000 , relevant for the nginx reverse proxy file lower down.

{
  "database": {
    "directory": "waspdb"
  },
  "logger": {
    "level": "debug",
    "disableCaller": false,
    "disableStacktrace": true,
    "encoding": "console",
    "outputPaths": [
      "stdout",
      "wasp.log"
    ],
    "disableEvents": true
  },
  "network": {
    "bindAddress": "0.0.0.0",
    "externalAddress": "auto"
  },
  "node": {
    "disablePlugins": [],
    "enablePlugins": []
  },
  "webapi": {
    "bindAddress": "127.0.0.1:9090"
  },
  "dashboard": {
    "auth": {
      "scheme": "basic",
      "username": "xxadmin",
      "password": "FgDR54notthis"
    },
    "bindAddress": "127.0.0.1:7000"
  },
  "peering": {
    "port": 4000,
    "netid": ":4000"
  },
  "nodeconn": {
    "address": "127.0.0.1:5000"
  },
  "nanomsg": {
    "port": 5550
  }
}

                

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _



IMPORTANT. DO NOT MAKE CHANGES DIRECTLY TO THE REVERSE PROXY FILE IF USING SWARM - SWARM WILL USUALLY OVERRIDE THEM

The Wasp Reverse Proxy Files

As described above, the reverse proxy setup by SWARM uses nginx so the files are in: /etc/nginx/sites-enabled where there is one for each different port setting on the main domain. If you have all of the nodes set by SWARM then it will contain all of these

bee default goshimmer hornet wasp-api wasp-dashboard

IMPORTANT. Note that there are TWO entries relating to WASP not one as in the other nodes.


An example Wasp 'wasp-dashboard' file is below with a few lines removed to make the remainder clearer. Notice that at the top there is the domain name, and at the bottom it is listening on port 446 which was defined earlier in SWARM as the Wasp reverse proxy port. The next most important areas are the 'location' sections. The one with 'dashboard' in does a 'proxy pass' to local port 7000. That was the port set in the config.json file above for the dashboard.

Also see the third location section which redirects the default request on port 447 to the SWARM landing page at /var/www/html/swarm-nodes/ NB This one may not be in the SWARM settings

server {
        server_name v2202110158313xxxxxx.ultrasrv.de;

        server_tokens off;
        ssl_session_cache shared:SSL:32m;
        add_header Strict-Transport-Security 'max-age=63072000; includeSubdomains' always;
        add_header X-Content-Type-Options "nosniff";
 
        'Authorization,Accept,Origin,DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-Wi>
        add_header 'Access-Control-Allow-Methods' 'GET,HEAD,PUT,PATCH,POST,DELETE';
        proxy_headers_hash_max_size 512;
        proxy_headers_hash_bucket_size 128;

        location ~ ^/(peering|chains|chain) {
                proxy_pass http://localhost:7000;
                proxy_http_version  1.1;
                proxy_cache_bypass  $http_upgrade;
                proxy_pass_request_headers on;
                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 Connection "keep-alive";
                sub_filter_once off;
                sub_filter 'href="/"' 'href="/dashboard"';
        }

        location /dashboard {
                proxy_pass http://localhost:7000/;
                proxy_http_version  1.1;
                proxy_cache_bypass  $http_upgrade;
                proxy_pass_request_headers on;

                                proxy_set_header        X-Real-SslId $ssl_session_id;
                proxy_set_header        X-Forwarded-For   $proxy_add_x_forwarded_for;
                proxy_set_header        X-Forwarded-Proto $scheme;
                proxy_set_header        X-Forwarded-Host  $host;
                proxy_set_header        X-Forwarded-Port  $server_port;
                proxy_set_header Connection "keep-alive";
                sub_filter_once off;
                sub_filter 'href="/"' 'href="/dashboard"';
        }

        location / {
                gzip off;
                alias /var/www/html/swarm-nodes/;
                index index.html;
                try_files $uri $uri/ =404;
        }

    listen [::]:446 ssl http2;
    listen 446 ssl http2;
    ssl_certificate /etc/letsencrypt/live/v2202110158313xxxxxx.ultrasrv.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/v2202110158313xxxxxx.ultrasrv.de/privkey.pem;
}


The second reverse proxy file, the one for the api is called wasp-api and is again in: /etc/nginx/sites-enabled. It looks like below. Note that the proxy_pass from port 448 (as set above for the Wasp api) is to local port 9090 - as set in the config.json for the webapi.

    server {
        server_name v2202110158313xxxxxx.ultrasrv.de;

        server_tokens off;
        ssl_session_cache shared:SSL:32m;
        add_header Strict-Transport-Security 'max-age=63072000; includeSubdomains' always;
        add_header X-Content-Type-Options "nosniff";
        add_header X-XSS-Protection "1; mode=block";
        add_header Access-Control-Allow-Origin $http_origin;
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Credentials' 'true';
        add_header 'Access-Control-Allow-Headers' 'Authorization,Accept,Origin,DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-M>
        add_header 'Access-Control-Allow-Methods' 'GET,HEAD,PUT,PATCH,POST,DELETE';
        proxy_headers_hash_max_size 512;
        proxy_headers_hash_bucket_size 128;

        location / {
                include /etc/nginx/wasp/webapiauth.conf;
                default_type  application/json;
                proxy_pass http://localhost:9090;
                proxy_pass_request_headers on;
                proxy_set_header        Host $host;
                proxy_set_header        X-Real-IP $remote_addr;
                proxy_set_header        X-Real-SslId $ssl_session_id;
                proxy_set_header        X-Forwarded-For   $proxy_add_x_forwarded_for;
                proxy_set_header        X-Forwarded-Proto $scheme;
                proxy_set_header        X-Forwarded-Host  $host;
                proxy_set_header        X-Forwarded-Port  $server_port;
                proxy_set_header Connection "keep-alive";
        }

    listen [::]:448 ssl http2;
    listen 448 ssl http2;
    ssl_certificate /etc/letsencrypt/live/v2202110158313xxxxxx.ultrasrv.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/v2202110158313xxxxxx.ultrasrv.de/privkey.pem;
}




_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

While you are here, why not also visit the main area of the TangleDust.com website. We are always keen to hear about more International projects to list.

Iota Smart Cities
Iota Identity and Trust
Iota Climate and eHealth
Iota Transport and Mobility