Kannisto.org

Arrowhead: Quickstart

The main purpose of the blog posts is to persist some instructions I have written for myself. However, I'm happy if someone else finds these beneficial too.

– Petri Kannisto

Introduction

Arrowhead is a framework for distributed, service-oriented systems (see https://projects.eclipse.org/projects/iot.arrowhead). It provides features, such as service registry, discovery, and orchestration, among others.

I wanted to quickly try Arrowhead, but as this appeared difficult with the existing instructions, I decided to write this guide. Although Arrowhead comes with a README, this is notorious of being badly written (sorry!) and contains errors as well as lacks some essential information. This guide hopefully provides some troubleshooting and additional steps. I also hope this stands time and won't be obsolete after a few months.

This guide assumes you have prior knowledge about Linux command line and Java, and you should know what Maven is. If you lack this knowledge, be ready to search and learn. The guide also assumes you know what Arrowhead is, as otherwise you likely wouldn't want to try it.

Special thanks to Minh for tips and to Mikael who gave tips to Minh!

Alternative approaches

It took me a while to understand why there are overlapping instructions for Debian-based systems. I assume this is just an alternative.

In the README, there's also information about how to use Docker, but this won't save you from building the system. That is, the Dockerfile won't build you anything without the JARs you have to generate by yourself.

Environment

These steps are likely to work in a variety of setups. I had the following:

The Arrowhead version was 4.6.0.

The steps

1. Clone Arrowhead from Github

git clone https://github.com/eclipse-arrowhead/core-java-spring.git

2. Install MySQL 5.7

AFAIK, you'll need MySQL 5.7 to run the setup scripts so I started with this legacy version.

I followed these instructions: https://computingforgeeks.com/how-to-install-mysql-on-ubuntu-focal/

If you just want to run local experiments, you can use an empty password for the root. This may save you from some annoyance. However, as you likely know, this is a bad idea in any system visible to anyone except your locally executing software.

3. SQL setup

Next, try the following commands in the scripts folder:

mysql -u root < create_empty_arrowhead_db.sql
mysql -u root < create_arrowhead_tables.sql

This failed at first because multiple timestamp fields lacked a default value in create_arrowhead_tables.sql. Each time the command fails, edit create_arrowhead_tables.sql to add the respective default value. These are many so you may search for all lines that lack the default.

For example, you would change this:

`updated_at`  TIMESTAMP   NOT NULL ON UPDATE CURRENT_TIMESTAMP,

...to this:

`updated_at`  TIMESTAMP   NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

Once the timestamps caused no issues, the script failed to create the user gams_knowledge. If this happens, login to MySQL console as below. The command assumes you have set an empty root password.

mysql -u root

In the console, run:

CREATE USER 'gams_knowledge'@'localhost';
CREATE USER 'gams_knowledge'@'%';

Try the SQL command(s) again to see if they succeed.

4. Build

Navigate to the folder core-java-spring and run:

mvn install -DskipTests

If everything is OK, the build should eventually finish successfully. In my machine, this took some 10 minutes.

5. Upgrade MySQL to 8.0

It appeared Arrowhead didn't start with MySQL 5.7. For instructions to upgrade to 8.0, see https://stackoverflow.com/questions/49963923/how-do-i-update-mysql-5-7-to-the-new-mysql-8-0

6. Set up non-secure mode

AFAIK, it is difficult to run Arrowhead in the secure mode. However, for a quick, local experiment, you need no security features. (Do this at your own risk!)

To set the core services non-secure, in these files...

...disable SSL/TLS (this line presumably already exists with the value true):

server.ssl.enabled=false

7. Start the core services

Arrowhead has three mandatory core services: service registry, authorization, and orchestrator. There are more, but these three are strictly required.

Navigate the console to the target folder of each service, i.e.:

...and start the JAR package in each folder (replace the placeholder with the service name):

java -jar arrowhead-[SERVICENAME]-4.6.0.jar

If everything goes well, you won't see a stacktrace and each service keeps running. You can try the API of each service with a browser: