Skip to content
Ansible playbook to install and configure goshimmer
Branch: master
Clone or download
Latest commit a01803d Aug 20, 2019

GoShimmer Playbook

Table of contents


Tested on the following operating systems:

  • CentOS 7.x
  • Ubuntu 16/18.04LTS
  • Debian 9.5 and 10
  • Raspbian 9.9 and 10 (Tested with Raspberry Pi 4 - 4GB RAM)


  • RAM: At least 1.5GB RAM, as less than this can result in out-of-memory failures.
  • x2 CPUs are recommended


Run (as root):

bash <(curl -s

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 and run-screen (read below).

Docker Usage Commands

These are just a few helpful commands to help you find your way around docker:

Docker Images

List all images

docker images

The 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.58MB

Note 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:af1fee9

View Docker Containers

View all docker containers:

docker ps -a

GoShimmer Help Output

Run 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 --help

You 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/goshimmer

On Ubuntu/Debian/Raspbian:

grep ^TAG /etc/default/goshimmer


In 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

Control GoShimmer

Goshimmer app start:

systemctl start goshimmer

You can also replace start with stop or restart.

GoShimmer logs follow:

journalctl -u goshimmer -e -f

Goshimmer Controller

A GUI utility has been added to help manage some basics like controlling the server, viewing logs, upgrading goshimmer etc.

Make sure you are root (sudo su) and run:


Goshimmer DB

The database is located in /var/lib/goshimmer/mainnetdb

Goshimmer Web

Since August 3rd 2019 nginx has been added to serve as a reverse proxy for some of goshimmer's common services.

Spammer is accessible via the web-browser on port 18080, e.g.: https://your-ip:18080/spammer. Note that you'll have to append a command to the URL, e.g: cmd=start or stop... See Spam Test below.

Dashboard is accessible via the web-browser on port 18081, e.g.: https://your-ip:18081/dashboard.

NOTE You can safely ignore the browser's warning about the certificate, as a self-signed one has been generated during the installation.

Spam Test

No need to open ports, forward ports etc, no need for browser. You can run on the commandline:

curl "http://localhost:8080/spammer?cmd=start"

You can add the parameter "tps=" to specify how many TPS to spam with, for example:

curl "http://localhost:8080/spammer?cmd=start&tps=100"

To stop:

curl "http://localhost:8080/spammer?cmd=stop"

See the statusscreen

Since Saturday, July 27 a new script has been added to help run goshimmer with the status screen. If you already have the playbook installed, don't worry, you can run the initial installation command to get the script ready!

To activate the screen run:

sudo run-screen

Use CTRL-c to exit.

If you want to leave the server running with this screen you need to run it within what is called a screen session.

Please refer to this article on how to use screen (you might need to install it):

Update the run-screen script or gosc

To update any scripts provided by this playbook simply use gosc and select to update gosc and scripts option from the menu.


Install Alongside IRI-Playbook

It is possible to run this installation on an IRI-playbook node. You must have enough RAM and CPU power to accommodate both.

A few notes:

  • This has only been tested in the case where you already have a Dockerized IRI-playbook node and run this installer afterwards.
  • GoShimmer-playbook re-uses IRI's HTTPS configuration (SSL certificate)
  • You will also be able to access the web services using the user you have configured for IRI


If you liked this playbook, and would like to leave a donation you can use this IOTA address:

You can’t perform that action at this time.