This repository installs a fully operational IOTA GOSHIMMER node.
Table of contents
- Requirements
- Recommendations
- Installation
- Docker Usage Commands
- Configuration
- Control GoShimmer
- Ports and URLs
- Connect to Wallet
- Troubleshooting
- Donations
Tested on the following operating systems:
- CentOS 7.x, CentOS 8.x
- Ubuntu 18/19/20.04LTS
- Debian 9.5 and 10
- Raspbian 9.9 and 10 (Tested with Raspberry Pi 4 - 4GB RAM)
Architectures (x86_64, arm/aarch 64 bit)
- RAM: At least 2GB RAM, as less than this can result in out-of-memory failures.
- x2 CPUs are recommended
You can first download the script to inspect it before running it, or run it directly:
sudo bash -c "bash <(curl -s https://raw.githubusercontent.com/nuriel77/goshimmer-playbook/main/goshimmer_install.sh)"This pulls the installation file from the root of this repository and executes it.
The installation will:
- Install latest GoShimmer and start it up.
- Configure basic security (firewalls) and open all required ports for GoShimmer to operate.
- Install nginx as a reverse proxy to access GoShimmer's Dashboard, spammer, etc.
- Add some helpful tools, e.g.:
gosc
If you are working on a fork in a feature branch or happen to directly contribute to this repository you can run the installer as user root, pointing it to the appropriate branch, e.g.:
BRANCH="dev-branch"; GIT_OPTIONS="-b $BRANCH" bash <(curl -s "https://raw.githubusercontent.com/nuriel77/goshimmer-playbook/$BRANCH/goshimmer_install.sh")These are just a few helpful commands to help you find your way around docker:
List all images
docker imagesThe output will look something like:
REPOSITORY TAG IMAGE ID CREATED SIZE
iotaledger/goshimmer 588e0ff 506e4a44db0d 2 days ago 23MB
iotaledger/goshimmer af1fee9 ffef5d662ba0 6 days ago 23MB
nginx latest e445ab08b2be 2 weeks ago 126MB
golang 1.12-alpine 6b21b4c6e7a3 4 weeks ago 350MB
alpine latest b7b28af77ffe 4 weeks ago 5.58MBNote that an image consists of a "REPOSITORY" name and a "TAG". Above we have 2 iotaledger/goshimmer images. The older can be deleted if no longer in use.
Delete a certain image (or example an older version of goshimmer you don't use anymore):
docker rmi iotaledger/goshimmer:v0.1View all docker containers:
docker ps -aRun goshimmer with --help: given that we know the image name and the tag. A quick way to get the tag variable configured:
docker run --rm -it iotaledger/goshimmer:9fda4b8 --helpYou can get the tag by viewing all images, or check the configuration file to see what is the currently used TAG:
On CentOS:
grep ^TAG /etc/sysconfig/goshimmerOn Ubuntu/Debian/Raspbian:
grep ^TAG /etc/default/goshimmerIn the file below we can specify the image and tag to use. In addition we can configure which command line arguments to pass to goshimmer:
-
On Ubuntu:
/etc/default/goshimmer -
On CentOS:
/etc/sysconfig/goshimmer
Goshimmer app start:
systemctl start goshimmerYou can also replace start with stop or restart.
GoShimmer logs follow:
journalctl -u goshimmer -e -fA GUI utility has been added to help manage some basics like controlling the server, viewing logs, upgrading goshimmer etc.
Run:
sudo goscOnce a new version of Goshimmer is released you should get a notification about it when running gosc.
Please note that since Goshimmer is still in development phase, you'll most likely have to first stop Goshimmer, delete the existing database and only then proceed to upgrade. Before upgrading via gosc please run sudo systemctl stop goshimmer && sudo rm -rf /var/lib/goshimmer/mainnetdb/* (will take a moment to execute).
The database is located in /var/lib/goshimmer/mainnetdb
Goshimmer dashboard is accessible by default via your public IP and port 8081. e.g:
https://mydomain.io
You can login using the username and password you've selected during the installation.
NOTE You can safely ignore the browser's warning about the certificate, as a self-signed one has been generated during the installation.
If you'd like to add a valid HTTPS/TLS certificate use gosc to request a certificate for your node. You must have a DNS A record pointing to your node's IP.
If you've enabled the spammer plugin (e.g. via gosc) you can start or stop spamming from the commandline.
No need to open ports, forward ports etc, no need for browser. You can run on the commandline:
curl "http://localhost:8012/spammer?cmd=start"You can add the parameter "tps=" to specify how many TPS to spam with, for example:
curl "http://localhost:8012/spammer?cmd=start&tps=100"To stop:
curl "http://localhost:8012/spammer?cmd=stop"Note that for security reasons the spammer is not made available on the browser by default.
You can enable it on the browser by running:
grep -q "^goshimmer_webapi_external_address: 0.0.0.0" /opt/goshimmer-playbook/group_vars/all/z-installer-override.yml || echo "goshimmer_webapi_external_address: 0.0.0.0" >> /opt/goshimmer-playbook/group_vars/all/z-installer-override.yml
Then run the following to apply the change:
cd /opt/goshimmer-playbook && ansible-playbook -i inventory site.yml -v --tags=nginx_roleFor the browser use https and port 8080. You will also have to login.
Here's a list of ports configured by the playbook by default. External communication for dashboard, webapi grafana etc. goes via nginx that serves as a reverse proxy. Other ports (fpc, gossip and autopeering) are exposed directly on the host.
| NAME | PORT INTERNAL | PORT EXTERNAL | PROTOCOL | PATH | DESCRIPTION |
|---|---|---|---|---|---|
| Autopeering | 14626 | 14626 | UDP | n/a | Autopeering |
| Gossip | 14666 | 14666 | TCP | n/a | Gossip |
| FPC | 10895 | 10895 | TCP | n/a | FPC |
| WebAPI | 8012 | 443 | TCP | /api | Web API (e.g. for Wallet) |
| Dashboard | 8011 | 443 | TCP | /dashboard | Main dashboard |
| Grafana | 3000 | 443 | TCP | /grafana | Grafana monitoring |
| Prometheus | 9090 | 443 | TCP | /prometheus | Prometheus metrics |
| Alertmanager | 9093 | 443 | TCP | /alertmanager | Alertmanager for prometheus |
All the external ports have been made accessible in the firewall. There is no need to configure the firewall on the node.
If you are running the node in an internal network/lan you have to forward at least the following ports from the router to the node:
80/tcp, 443/tcp, 10895/tcp, 14666/tcp, 14626/udp
Run the following commands if you want to connect to your node's API without having to go through HTTPS (this is a discouraged practice when goshimmer goes live).
grep -q "^goshimmer_webapi_internal_address: 0.0.0.0" /opt/goshimmer-playbook/group_vars/all/z-append.yml || echo "goshimmer_webapi_internal_address: 0.0.0.0" >> /opt/goshimmer-playbook/group_vars/all/z-append.ymlThen run:
run-playbook --tags=goshimmer_config_file -e overwrite=yes && ufw allow 8012The node will be accessible via IP or DNS name, e.g.: http://my-node-ip:8012
The wallet connects to the /api/ path. For example https://my-node.io/api/.
Note that by default the goshimmer-playbook forces HTTPS connections to the node. The wallet requires a valid HTTPS certificate when HTTPS is used. You can request a certificate for your node via gosc. You'll need a DNS pointing to your node's IP.
Alternatively, you can follow Expose WebApi Connection On HTTP while goshimmer is still not on mainnet.
If something isn't working as expected, try to gather as much data as possible, as this can help someone who is able to help you finding out the cause of the issue.
If anything is wrong related to Goshimmer, first thing to look at are Goshimmer's logs. See how to get logs in Control GoShimmer chapter.
To check if Goshimmers's API port is listening you can use the command to see if any output (use 8011 or 8012 as port number):
sudo lsof -Pni:8011Note that after restarting Goshimmer it might take some time to see the port available.
If you receive this error when trying to browse to the dashboard then:
- nginx (the webserver/proxy) is working properly
- the back-end to which it is trying to connect isn't working properly (goshimmer).
Nginx takes requests from the web and forwards those internally. For example, https://my-site.io tells nginx to connect to Goshimmers's dashboard. If Goshimmer is inactive (crashed? starting up?) then nginx would not be able to forward your requests to it. Make sure that Goshimmer is working properly, e.g. checking logs: see Control GoShimmer. Note that when checking the logs, start from the bottom of the logs and scroll up to the line where you see the error began.
You will probably get this message when trying to connect to the dashboard using your IP address.
Other messages might claim certificate is invalid for the domain.
You can safely proceed (most browsers allow to bypass the warning). If you have a DNS pointing to your node's IP address you can use gosc to request a HTTPS certificate. That will allow to connect from browsers or the wallet safely to your node.
In the following link you can read more about how to collect logs from your system. Although this documentation is for IRI, the commands are similar (just replace iri with hornet if needed):
https://iri-playbook.readthedocs.io/en/master/troubleshooting.html#troubleshooting
You can rerun the playbook to fix most issues. Use the tool gosc, there's an option to rerun the playbook.
If gosc isn't working, try the following command:
cd /opt/goshimmer-playbook && git pull && ansible-playbook -v site.yml -i inventory -e overwrite=yesThis command will reset all configuration files and restart any required services.
To create, test and maintain this playbook requires many hours of work and resources. This is done wholeheartedly for the IOTA community.
If you liked this project and would like to leave a donation you can use this IOTA address:
iota1qpsszw7jnknct8960t80ffxn2hmx8wrrrw69ca3us6u5kt92c2hhj8s7ccf
No IOTA? ⭐ the project is also a way of saying thank you! 😎