Orion-LD Version 20200318 - Installationsanleitung
←
→
Transkription von Seiteninhalten
Wenn Ihr Browser die Seite nicht korrekt rendert, bitte, lesen Sie den Inhalt der Seite unten
CEF-Kontextbroker
T06 - Pflege der technischen Dokumentation
und der technischen Handbücher
Version 20200318
Orion-LD
Installationsanleitung
18.03.2020Inhaltsverzeichnis
1 Übersicht 4
2 Einleitung 5
3 Unterstützte Linux-Distributionen 5
4 Installationsmethoden 5
4.1 Docker-Images 5
4.2 Aus Quellcode erstellen 6
4.2.1 Funktionstest 6
5 Installationsanleitung für Ubuntu 18.04.3 10
5.1 Installation von abhängigen Paketen 11
5.2 Herunterladen und Erstellen von abhängigen Bibliotheken aus Quellcode 11
5.2.1 MongoDB-Treiber 12
5.2.2 libmicrohttpd 12
5.2.3 rapidjson 12
5.2.4 kbase 13
5.2.5 klog 13
5.2.6 kalloc 13
5.2.7 kjson 13
5.2.8 khash 14
5.3 Quellcode von Orion-LD 14
5.4 Installation des MongoDB-Servers 15Dokumenteigenschaften Eigenschaft Wert Veröffentlichung: 18.03.2020 Status: Endfassung Version: 20200318 Autoren: Ken Gunnar Zangelin Geprüft von: Stefano De Panfilis Genehmigt von: Versionsverlauf Version Beschreibung Datum 20200318 Dokument zur Prüfung eingereicht 18.03.2020
1 Übersicht Bei dem vorliegenden Dokument handelt es sich um das Orion-LD-Installationshandbuch, das auf der derzeitigen Software-Version und Dokumentation beruht. D.h. zu diesem Zeitpunkt beziehen sich die beschriebenen Vorgehensweisen auf die aktuelle Orion-LD Alpha Release 1. Aus diesem Grund bitten wir den Leser, auf dem offiziellen Orion-LD GitHub Repository nach aktuellen Updates zu suchen: https://github.com/FIWARE/context.Orion-LD
2 Einleitung
Orion-LD ist ein NGSI-LD Publish/Subscribe Broker (oder: Kontextbroker).
Um Orion-LD, Alpha Release 1, zu installieren, können Sie
● ein vorgefertigtes Docker-Image verwenden, oder
● den Broker aus dem Quellcode kompilieren.
Derzeit läuft Orion-LD nur unter Linux. Es gab bisher keine Bestrebungen, Orion-LD auch
auf anderen Betriebssystemen zu betreiben. MacOS wäre die nächste naheliegende
Alternative und falls sich jemand damit freiwillig beschäftigen möchte, wäre dies ein sehr
willkommener Beitrag.
3 Unterstützte Linux-Distributionen
Die Referenzdistribution für den Orion-LD NGSI-LD Kontextbroker ist Ubuntu 18.04.
Obwohl Orion-LD auch unter CentOS, Debian oder anderen Versionen von Ubuntu
einwandfrei funktioniert, ist die einzige offiziell unterstützte Distribution Ubuntu 18.04.
4 Installationsmethoden
4.1 Docker-Images
Docker-Images für Ubuntu und CentOS werden für jeden Pull-Request erstellt, der in den
develop Branch gemerged wird. Um das Orion-LD Docker-Image zu erstellen und
auszuführen, müssen Docker und Docker Compose installiert sein. Ein Beispiel für die
Datei docker-compose.yml finden Sie weiter unten:
version: "3.5"
services:
# Orion ist der Kontextbroker
orion:
image: fiware/orion-ld
hostname: orion
container_name: fiware-orion
depends_on:
- mongo-db
expose:
- "1026"
ports:
- "1026:1026"
command: -dbhost mongo-db -logLevel DEBUG
healthcheck:
test: curl --fail -s http://orion:1026/version || exit 1
# Datenbanken
mongo-db:
image: mongo:3.6
hostname: mongo-db
container_name: db-mongoexpose:
- "27017"
ports:
- "27017:27017"
command: --nojournal
volumes:
- mongo-db:/data
volumes:
mongo-db: ~
Wir stellen auch CentOS- und Debian-basierte Dockerfiles zur Verfügung, um die
Erstellung Ihrer eigenen Images zu erleichtern. Sie finden sie an dieser Stelle zusammen
mit der Dokumentation, die beschreibt, wie jedes von ihnen zu verwenden ist.
Ein öffentliches Image ist auch auf Docker Hub verfügbar.
4.2 Aus Quellcode erstellen
Als erstes muss das Betriebssystem installiert werden. Wie bereits erwähnt, läuft Orion-
LD auf einer Vielzahl von Linux-Plattformen. Ubuntu 18.04 LTS ist die offiziell
unterstützte Distribution, aber Orion-LD funktioniert potenziell auf jeder modernen
Linux-Distribution.
Um Orion-LD aus dem Quellcode zu installieren, folgen Sie bitte den Anweisungen für
Ihre gewählte Distribution.
Installationsanleitungen für verschiedene Distributionen:
● Ubuntu 18.04.3 LTS - die offizielle Distribution
● CentOS 7
● Debian 9
4.2.1 Funktionstest
Nun, da Sie Orion-LD kompiliert und installiert haben und der MongoDB-Server läuft,
sollte der Broker funktionieren. Um dies sicherzustellen, starten wir ihn und führen ein
paar einfache Befehle aus.
Stellen Sie zunächst sicher, dass der MongoDB-Server auch läuft:
ps aux | grep mongodb
Beispielausgabe, wenn MongoDB läuft:
mongodb 27265 7.5 3.9 1115980 79720 ? Ssl 11:34 0:00
/usr/bin/mongod --config /etc/mongod.conf
Falls er nicht läuft (kein /usr/bin/mongod Prozess in der vorherigen Ausgabe
gefunden), starten Sie ihn bitte:
sudo service mongod start
In der MongoDB-Dokumentation können Sie bei Bedarf nachschauen, wie Sie ihn beim
Booten automatisch starten lassen können.Starten wir den Broker in einem separaten Fenster im Vordergrund:
orionld -fg
In einem weiteren Fenster senden wir curl-Befehle an den Broker. Zuerst müssen wir
natürlich curl installieren :):
curl localhost:1026/ngsi-ld/ex/v1/version
Sie sollten einen ähnlichen Response wie diesen sehen:
kz@ubuntu:~$ curl localhost:1026/ngsi-ld/ex/v1/version
{
"@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-
context.jsonld",
"branch": "develop",
"kbase version": "0.2",
"kalloc version": "0.2",
"kjson version": "0.2",
"boost version": "1_65_1",
"microhttpd version": "0.9.48-0",
"openssl version": "OpenSSL 1.0.2n 7 Dec 2017",
"mongo version": "1.1.2",
"rapidjson version": "1.0.2",
"libcurl version": "7.58.0",
"libuuid version": "UNKNOWN",
"Next File Descriptor": 18
}
Sie werden vermutlich auch die Ausgabe von Traces im Terminal des Brokers
bemerken.
Nun lassen Sie uns eine Entität erstellen:
curl localhost:1026/ngsi-ld/v1/entities -d '{ "id": "urn:entities:E1",
"type": "T", "P1": { "type": "Property", "value": 12 }}' -H 'Content-Type:
application/json' --dump-header /tmp/httpHeaders.out
curl gibt nur die Payload-Daten des Response auf dem Bildschirm aus und da eine
Entitätserstellung keine Payload-Daten hat, werden Sie nichts sehen (es sei denn, es liegt
ein Fehler vor). Sie können überprüfen, ob der curl-Befehl funktioniert hat, indem Sie den
folgenden Befehl eingeben (direkt nach dem curl-Befehl):
echo $?
$? ist eine Umgebungsvariable, die den Rückgabecode des zuletzt ausgeführten Shell-
Befehls speichert. Null bedeutet OK, alles andere bedeutet einen Fehler.
Es gibt keine Payload-Daten im Response, aber es ist möglich die HTTP-Header des
Response zu sehen, da die Option --dump-header /tmp/httpHeaders.out benutzt
wurde. Um die resultierenden HTTP-Header zu sehen, verwenden Sie dann z.B. den
folgenden Befehl:
cat /tmp/httpHeaders.outErwartete HTTP-Header:
HTTP/1.1 201 Created
Connection: Keep-Alive
Content-Length: 0
Link: ;
rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
Location: /ngsi-ld/v1/entities/urn:entities:E2
Date: Tue, 19 Nov 2019 18:56:01 GMT
Fügen Sie also --dump-header /tmp/httpHeaders.out dem curl-Request hinzu, um die
HTTP-Header mitzuschneiden und verwenden Sie den Befehl cat, um den Inhalt der
Datei anzusehen (/tmp/httpHeaders.out).
Wenn alles geklappt hat, wurde mit dem vorherigen curl-Kommando eine Entität
erstellt. Sie kann in MongoDB z.B. mit dem folgenden Befehl ausgegeben werden:
echo 'db.entities.findOne()' | mongo mongodb://localhost:27017/orion
Erwarteter Response:
kz@ubuntu:~$ echo 'db.entities.findOne()' | mongo
mongodb://localhost:27017/orion
MongoDB shell version v4.0.13
connecting to: mongodb://localhost:27017/orion?gssapiServiceName=mongodb
Implicit session: session { "id" : UUID("9ece1fb7-df0d-41a3-8316-
042425351dd8") }
MongoDB server version: 4.0.13
{
"_id" : {
"id" : "urn:entities:E1",
"type" : "https://uri.etsi.org/ngsi-ld/default-context/T",
"servicePath" : "/"
},
"attrNames" : [
"https://uri.etsi.org/ngsi-ld/default-context/P1"
],
"attrs" : {
"https://uri=etsi=org/ngsi-ld/default-context/P1" : {
"type" : "Property",
"creDate" : 1574189638,
"modDate" : 1574189638,
"value" : 12,
"mdNames" : [ ]
}
},
"creDate" : 1574189638,
"modDate" : 1574189638,
"lastCorrelator" : ""
}
bye
Wenn Sie eine ähnliche Rückgabe wie die obige sehen: Herzlichen Glückwunsch, es
funktioniert alles!!!Wenn Sie sich die Daten in MongoDB genauer ansehen, werden Sie feststellen, dass der
Entitätstyp und der Name des Attributs nicht mehr exakt dem entsprechen, was Sie
eigentlich "angefragt" haben. Tatsächlich tun sie das aber. Dies ist ein gewolltes Verhalten
und ein wesentlicher Bestandteil von NGSI-LD. Kurz gesagt, der Kontext wurde
verwendet, um den Entitätstyp und den Attributnamen zu erweitern. Wie der Kontext
funktioniert, wird in Dokumenten und Tutorials zu NGSI-LD ausführlich erklärt. Wir
empfehlen mit dem Getting Started with Orion-LD Guide zu beginnen.
Abschließend fragen wir die erstellte Entität direkt beim Orion-LD ab, anstatt sie nur in
der Datenbank anzuschauen:
curl 'localhost:1026/ngsi-ld/v1/entities?type=T&prettyPrint=yes&space=2'
Die Ausgabe sollte genau so aussehen:
[
{
"id": "urn:entities:E1",
"type": "T",
"P1": {
"type": "Property",
"value": 12
}
}
]
Wie man erkennen kann, sind der Entitätstyp (T) und der Attributname (P1) keine langen
Namen mehr (diese befinden sich in der Datenbank). Der Grund dafür ist, dass der
Kontext zur Verdichtung der Werte benutzt wurde.
Wie jetzt? Bei diesen beiden Operationen wurde doch kein Kontext verwendet?
So ganz stimmt das nicht. Es wurde der Core-Kontext verwendet, aber es wurde kein
Benutzerkontext angegeben. Der Core-Kontext ist der Standardkontext und wenn kein
Kontext angegeben ist, wird dieser Core-Kontext standardmäßig verwendet.
Tatsächlich wird Orion-LD, selbst wenn der Benutzer einen Kontext angibt, immer noch
den Kernkontext verwenden und jedes Element, das im Kernkontext vorhanden ist, wird
das entsprechende Element (gleicher Key/Name) des vom Benutzer bereitgestellten
Kontextes überschreiben.
Der Kontext, der bei der Erstellung des Response verwendet wurde, wird im HTTP-Link-
Header zurückgegeben. Wenn Sie sich von curl wie bei der nachfolgenden GET-Operation
die HTTP-Headern ausgeben lassen (d.h. unter Verwendung der Option --dump-header
/tmp/httpHeaders.out):
curl 'localhost:1026/ngsi-ld/v1/entities?type=T&prettyPrint=yes&space=2' -
-dump-header /tmp/httpHeaders.out
dann können Sie sich die HTTP-Header anzeigen lassen mit
cat --dump-header /tmp/httpHeaders.out
was folgendes ausgibt:HTTP/1.1 200 OK
Connection: Keep-Alive
Content-Length: 120
Content-Type: application/json
Link: ;
rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
Date: Wed, 20 Nov 2019 11:49:04 GMT
https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld - das ist der Core-Kontext!
Wenn Sie stattdessen Orion-LD den Kontext innerhalb der Payload-Daten
zurückzugeben lassen (was geschieht, wenn der Accept-Header auf application/ld+json
gesetzt wird):
curl 'localhost:1026/ngsi-ld/v1/entities?type=T&prettyPrint=yes&space=2' -
H "Accept: application/ld+json"
dann würde die Antwort so lauten:
[
{
"@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-
context.jsonld",
"id": "urn:entities:E1",
"type": "T",
"P1": {
"type": "Property",
"value": 12
}
}
]
und es gäbe keinen HTTP-Link-Header.
Die Installationsanleitung wäre dann damit erstmal abgeschlossen.
Wenn Sie Tests durchführen möchten, um wirklich sicherzugehen, dass Ihr Orion-LD
Kontextbroker korrekt funktioniert, folgen Sie bitte den Anweisungen in Ihrem
jeweiligen Installationshandbuch für Funktionstests:
● Ubuntu 18.04.3
● CentOS 7
● Debian 10
Wie man die Unit-Tests durchführt (es gibt keine spezifischen Unit-Tests für den NGSI-
LD-Teil, nur älteres Orion-Material), wird hier beschrieben.
5 Installationsanleitung für Ubuntu 18.04.3
Für diese Anleitung wurde Ubuntu 18.04.3 LTS (Desktop-Image) von hier
heruntergeladen und als virtuelle Maschine unter VMWare installiert.5.1 Installation von abhängigen Paketen
Installation per Paketmanager:
● boost (viele Bibliotheken)
● libssl1.0
● libcurl4
● libsasl2
● libgcrypt
● libuuid
Nun muss eine ganze Reihe von Paketen installiert werden. Ich persönlich ziehe aptitude
apt-get vor, daher ist das erste, was ich tue, aptitude zu installieren:
sudo apt-get install aptitude
Für die Kompilierung und das Testen benötigte Werkzeuge:
sudo aptitude install build-essential cmake scons curl
Bibliotheken, die nicht aus Quellcode erstellt werden:
sudo aptitude install libssl1.0-dev gnutls-dev libcurl4-gnutls-dev
libsasl2-dev \
libgcrypt-dev uuid-dev libboost-dev libboost-regex-
dev libboost-thread-dev \
libboost-filesystem-dev
5.2 Herunterladen und Erstellen von abhängigen Bibliotheken aus
Quellcode
Einige Bibliotheken werden aus Quellcode erstellt und diese Quellen müssen
heruntergeladen und kompiliert werden.
● Mongo Driver: legacy-1.1.2
● libmicrohttpd: 0.9.48
● rapidjson: 1.0.2
● kbase: 0.2
● klog: 0.2
● kalloc: 0.2
● kjson: 0.2
● khash: 0.2
● gtest: 1.5 (nur für Unit-Tests erforderlich)
● gmock: 1.5 (nur für Unit-Tests erforderlich)
Bibliotheken, die geklonte Repositories sind, halte ich selbst alle in einem Verzeichnis,
das ich git nenne, direkt unter meinem Home-Verzeichnis: ~/git. Diese Anleitung folgt
diesem Prinzip, daher beginnen wir mit der Erstellung des Verzeichnisses für
Repositories:
mkdir ~/git
Und da git verwendet werden wird, können wir es genauso gut installieren:sudo aptitude install git
5.2.1 MongoDB-Treiber
Da Orion-LD auf Orion basiert und Orion den alten Legacy C++-Treiber der MongoDB
Client-Bibliothek verwendet, benutzt Orion-LD ebenfalls diese alte Bibliothek. Es ist
geplant, zumindest alle NGSI-LD-Requests auf den neuesten C-Treiber des MongoDB-
Clients zu migrieren, aber mit dieser Arbeit wurde noch nicht begonnen.
Zum Herunterladen, Erstellen und Installieren:
sudo mkdir /opt/mongoclient
sudo chown $USER:$GROUP /opt/mongoclient # (1)
cd /opt/mongoclient
wget https://github.com/mongodb/mongo-cxx-driver/archive/legacy-
1.1.2.tar.gz
tar xfvz legacy-1.1.2.tar.gz
cd mongo-cxx-driver-legacy-1.1.2
scons --disable-warnings-as-errors --ssl --use-sasl-client
sudo scons install --prefix=/usr/local --disable-warnings-as-errors --ssl
--use-sasl-client
(1) Um Sie zum Eigentümer einer Datei zu machen, müssen Sie Ihren Benutzernamen
und Ihre Gruppe angeben. Die env var USER existiert bereits, aber wenn Sie diesen
"sudo chown"-Befehl kopieren und einfügen wollen, müssen Sie die env var GROUP
erstellen, um Ihre Gruppe widerzuspiegeln. In meinem Fall mache ich das:
export GROUP=kz
Danach sollten Sie die Bibliothek libmongoclient.a unter /usr/local/lib/ und das
Header-Verzeichnis mongo unter /usr/local/include/ finden.
5.2.2 libmicrohttpd
libmicrohttpd ist die Bibliothek, die sich um eingehende Verbindungen und http/https
kümmert. Wir verwenden eine ältere Version davon, die demnächst durch die neueste
Version ersetzt wird. So installieren Sie libmicrohttpd aus dem Quellcode:
sudo mkdir /opt/libmicrohttpd
sudo chown $USER:$GROUP /opt/libmicrohttpd
cd /opt/libmicrohttpd
wget http://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.48.tar.gz
tar xvf libmicrohttpd-0.9.48.tar.gz
cd libmicrohttpd-0.9.48
./configure --disable-messages --disable-postprocessor --disable-dauth
make
sudo make install
5.2.3 rapidjson
rapidjson ist der JSON-Parser, der von der NGSI APIv2-Implementierung verwendet wird.
Da Orion-LD ebenfalls NGSI APIv2 enthält, benötigen wir diese Bibliothek. Wie
libmicrohttpd verwenden wir eine ältere Version der Bibliothek. So installieren wir sie
aus dem Quellcode:sudo mkdir /opt/rapidjson sudo chown $USER:$GROUP /opt/rapidjson cd /opt/rapidjson wget https://github.com/miloyip/rapidjson/archive/v1.0.2.tar.gz tar xfvz v1.0.2.tar.gz sudo mv rapidjson-1.0.2/include/rapidjson/ /usr/local/include 5.2.4 kbase kbase ist eine Sammlung grundlegender Funktionen, wie z.B. die Behandlung von Zeichenketten, die von den übrigen "K-libs" verwendet wird. Zum Herunterladen, Erstellen und Installieren: cd ~/git git clone https://gitlab.com/kzangeli/kbase.git cd kbase git checkout release/0.3 make install 5.2.5 klog klog ist eine Bibliothek fürs Logging, die von den übrigen "K-libs" verwendet wird. Zum Herunterladen, Erstellen und Installieren: cd ~/git git clone https://gitlab.com/kzangeli/klog.git cd klog git checkout release/0.3 make install 5.2.6 kalloc kalloc ist eine Bibliothek, die eine schnellere Allokation ermöglicht, indem sie Aufrufe von malloc vermeidet. Die Bibliothek alloziert eine große Menge Pufferspeicher durch den Aufruf von malloc und gibt dann Teile dieses groß allozierten Speichers aus. Die Anteile können nicht freigegeben werden, sondern nur die großen Pufferspeicher, die über malloc zugewiesen werden, und das geschieht, wenn die kalloc-Instanz beendet wird. Für Orion-LD, der jeden Request in einem separaten Thread behandelt, ist dies mit Hinblick auf die Performance ideal. Zum Herunterladen, Erstellen und Installieren: cd ~/git git clone https://gitlab.com/kzangeli/kalloc.git cd kalloc git checkout release/0.3 make install 5.2.7 kjson kjson ist ein JSON-Parser, der aus der textuellen JSON-Eingabe einen einfach zu verwendenden KjNode-Baum aufbaut. Er ist sehr einfach zu verwenden (verknüpfte Listen) und um ein Vielfaches schneller als rapidjson, den Orion NGSI-v2 verwendet. Aus diesem Grund verwendet Orion-LD kjson anstelle von rapidjson.
Zum Herunterladen, Erstellen und Installieren: cd ~/git git clone https://gitlab.com/kzangeli/kjson.git cd kjson git checkout release/0.3 make install 5.2.8 khash khash ist eine Bibliothek, die eine Hash-Tabellen-Implementierung bereitstellt. Diese Hash-Tabelle wird für den Kontext-Cache von Orion-LD verwendet. Zum Herunterladen, Erstellen und Installieren: cd ~/git git clone https://gitlab.com/kzangeli/khash.git cd khash git checkout release/0.3 make install 5.3 Quellcode von Orion-LD Nun, da wir alle Abhängigkeiten installiert haben, ist es an der Zeit, das Orion-LD- Repository zu klonen: cd ~/git git clone https://github.com/FIWARE/context.Orion-LD.git cd context.Orion-LD make install Am Ende von make install will das Makefile die ausführbare Datei (orionld) nach /usr/bin kopieren und weitere Dateien nach /usr. Da die Kompilierung nicht als root (sudo) ausgeführt wurde (und auch nicht ausgeführt werden sollte), werden diese Kopiervorgänge fehlschlagen. Sie haben hier also zwei Möglichkeiten: 1. Erstellen Sie die Dateien manuell mit sudo und machen Sie sich dann zum Eigentümer dieser Dateien: sudo touch /usr/bin/orionld sudo chown $USER:$GROUP /usr/bin/orionld sudo touch /etc/init.d/orionld sudo chown $USER:$GROUP /etc/init.d/orionld sudo touch /etc/default/orionld sudo chown $USER:$GROUP /etc/default/orionld 2. Führen Sie sudo make install aus und lassen Sie die Dateien in den Besitz von root übergehen. Persönlich bevorzuge ich Option 1. Ich benutze sudo äußerst ungern. Sie haben nun orionld, den NGSI-LD Kontextbroker, kompiliert, installiert und einsatzbereit!
Außer natürlich, wenn Sie auch den MongoDB-Server installieren müssen. Bis jetzt haben wir nur die MongoDB Client-Bibliothek installiert, so dass orionld mit dem MongoDB- Server sprechen kann. 5.4 Installation des MongoDB-Servers Wenn Sie ein Docker-Image verwenden, wird der MongoDB-Server als Docker-Container bereitgestellt. Wenn Docker nicht verwendet wird, muss der MongoDB-Server installiert werden. Lesen Sie dazu bitte die MongoDB-Dokumentation. Die Version 4.0 ist die empfohlene, aber sowohl ältere als auch neuere Versionen sollten einwandfrei funktionieren. Die MongoDB-Dokumentation macht zu der Installation des MongoDB-Server 4.0 unter Ubuntu 18.04 folgende Vorgaben: # Öffentlichen MongoDB GPG Key importieren wget -qO - https://www.mongodb.org/static/pgp/server-4.0.asc | sudo apt- key add - # Sollte mit "OK" antworten # list-File /etc/apt/sources.list.d/mongodb-org-4.0.list erstellen echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list # Lokale Paket-Datenbank neuladen sudo apt-get update # MongoDB Pakete installieren sudo apt-get install -y mongodb-org Für weitere Details zum MongoDB-Installationsprozess oder falls etwas schief geht, lesen Sie bitte die MongoDB-Dokumentation.
Sie können auch lesen
