Tutoriel : Contribuer à Cesium+ Pod

Créez un compte GitHub

Si vous disposez déjà d'un compte GitHub, vous pouvez passer cette étape.

Rendez-vous sur https://git.duniter.org (site en anglais). Renseigner les 3 champs proposés :

• Nom d'utilisateur

• E-mail

• Mot de passe

Vous recevrez probablement un e-mail de confirmation qu'il vous faudra valider. Une fois cette étape passée, vous devriez disposer d'un compte GitHub .

Forkez le dépôt principal

Rendez-vous à l'adresse https://git.duniter.org/clients/cesium-grp/cesium-plus-pod. Cliquez sur le bouton « Fourcher » en haut de la page.

Installer Git

L'installation de Git dépend de votre système d'exploitation. Suivez simplement les indications présentes sur : https://git-scm.com/

Cloner votre fork

A ce stade, vous êtes en mesure de récupérer votre version du code source (votre fork), afin de pouvoir travailler dessus.

Ouvrez Git en ligne de commande

Pour récupérer le code source, lancez Git en mode console.

• Sous Linux et MacOS, ouvrez tout simplement le Terminal

• Sous Windows lancez le programme Git Bash :

git clone <coller l'URL copiée>

git clone git@git.duniter.org:clients/cesium-grp/cesium-plus-pod.git
Cloning into 'cesium-plus-pod'...
 (...)
Checking connectivity... done.

Installer JDK

• Sous Windows : Téléchargez puis installez un JDK (version 8 ou +) depuis le site web d'Oracle

• Sous Linux (Debian) : Lancez la commande suivante :

sudo apt-get install openjdk-8-jdk

Installer LibSodium

libsodium est une librairie de cryptographie.

• Sous Windows : Aucune instalation nécessaire (fichier sodium.dll déjà présent dans la librairie duniter4j incluse);

• Sous Linux : suivre les notes d'installation (anglais).

  • Après installation, vérifiez que le fichier libsodium.so existe bien dans /usr/local/lib ou /opt/local/lib.

  • S'il existe, mais à une autre eplacement, veuillez créez un lien symbolique à l'un ou l'autre de ces emplacements.

Installer Apache Maven 3

Installer les outils nécessaires pour la compilation :

• Installez Apache Maven 3
  • Sous Windows : téléchargez (version 3.x) puis installez en suivant ces instructions.
  • Sous Linux : Lancez la commande :

    sudo apt-get install maven

Installer un IDE

Pour développer en Java, vous pouvez utiliser l'IDE de votre choix, par exemple :

• Sublime Text (non libre) : https://www.sublimetext.com/
• Autre possibilité : Idea (non libre mais fonctionnement très avancé).

Configurer le projet

La configuration utilisée pour le développement est visible dans le fichier : /cesium-plus-pod-assembly/src/test/es-home/config/elasticsearch.yml

#
# Duniter node to synchronize
#
duniter.host: localhost
duniter.port: 10901    <- à remplacer par le port de votre noeud

#
# Duniter node to synchronize
#
duniter.host: g1.duniter.org
duniter.port: 10901

duniter.security.enable: false

Compiler le projet

La compilation du projet utilise Maven, par la commande mvn (à ne pas confondre avec nvm).

mvn install

(...)
[INFO] Building zip: /home/user/git/cesium-plus-pod/cesium-plus-pod-assembly/target/cesium-plus-pod-0.3.5-SNAPSHOT-standalone.zip
[INFO] 
[INFO] --- maven-install-plugin:2.4:install (default-install) @ cesium-plus-pod-assembly ---
[INFO] Installing /home/user/git/cesium-plus-pod/cesium-plus-pod-assembly/pom.xml to /home/eis/.m2/repository/org/duniter/cesium-plus-pod-assembly/0.3.5-SNAPSHOT/cesium-plus-pod-assembly-0.3.5-SNAPSHOT.pom
[INFO] Installing /home/user/git/cesium-plus-pod/cesium-plus-pod-assembly/target/cesium-plus-pod-0.3.5-SNAPSHOT-standalone.zip to /home/eis/.m2/repository/org/duniter/cesium-plus-pod-assembly/0.3.5-SNAPSHOT/cesium-plus-pod-assembly-0.3.5-SNAPSHOT-standalone.zip
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] Cesium+ pod :: Core plugin ........................ SUCCESS [8.954s]
[INFO] Cesium+ pod :: User plugin ........................ SUCCESS [1.039s]
[INFO] Cesium+ pod :: Subscription plugin ................ SUCCESS [0.804s]
[INFO] Cesium+ pod :: ElasticSearch Assembly ............. SUCCESS [4.747s]

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 48.733 s
[INFO] Finished at: 2016-11-17T11:06:16+01:00
[INFO] Final Memory: 74M/741M
[INFO] ------------------------------------------------------------------------

mvn install -DskipTests

Lancer un noeud ElasticSearch

Il ne vous reste plus qu'à lancer votre pod local.

Lancez la commande suivante :

mvn install -Prun -pl cesium-plus-pod-assembly

Vous devriez avoir maintenant :

[2016-11-17 13:29:35,874][INFO ][transport                ] [Att-Lass] publish_address {127.0.0.1:9300}, bound_addresses {[::1]:9300}, {127.0.0.1:9300}
[2016-11-17 13:29:35,882][INFO ][discovery                ] [Att-Lass] cesium-plus-pod-g1-TEST/HjDNQrTTSuyfmzGEbY7qNQ
[2016-11-17 13:29:38,956][INFO ][cluster.service          ] [Att-Lass] new_master {Att-Lass}{HjDNQrTTSuyfmzGEbY7qNQ}{127.0.0.1}{127.0.0.1:9300}, reason: zen-disco-join(elected_as_master, [0] joins received)
[2016-11-17 13:29:38,990][INFO ][http                     ] [Att-Lass] publish_address {127.0.0.1:9200}, bound_addresses {[::1]:9200}, {127.0.0.1:9200}
[2016-11-17 13:29:38,991][INFO ][node                     ] [Att-Lass] started
[2016-11-17 13:29:39,515][INFO ][gateway                  ] [Att-Lass] recovered [6] indices into cluster_state
[2016-11-17 13:29:41,655][INFO ][cluster.routing.allocation] [Att-Lass] Cluster health status changed from [RED] to [YELLOW] (reason: [shards started [[registry][1], [registry][1]] ...]).
[2016-11-17 13:29:45,756][INFO ][node                     ] Checking Duniter indices...
[2016-11-17 13:29:45,766][INFO ][node                     ] Checking Duniter indices... [OK]
[2016-11-17 13:29:58,052][INFO ][duniter.blockchain       ] [g1-test] [cgeek.fr:9330] Indexing last blocks...

Vérifier le fonctionnement

Pour vérifier le bon fonctionnement de votre noeud ES, ouvrez un navigateur à l'adresse suivante : http://127.0.0.1:9200 (il s'agit de l'adresse par défaut d'ElasticSearch).

Vous devriez voir le contenu suivant :

Bravo, votre pod Cesium+ est fonctionnel !

En cas de problème au lancement

# ---------------------------------- Network -----------------------------------
#
# Set the bind address to a specific IP (IPv4 or IPv6):
#
network.host: 192.168.233.1    <-- Remplacez par votre IP
#
# Set a custom port for HTTP:
#
http.port: 9200   <-- Remplacez par un port libre de votre machine (plage 9200-9300 par défaut)

Répérer les couches logicielles

Ouvrir votre IDE, et ouvrir le projet Duniter4j.

Dans le répertoire cesium-plus-pod-core/src/main/java, cherchez et répérez dans le code :

• les controlleurs REST : package org.duniter.elasticsearch.rest

• les services d'indexation : package org.duniter.elasticsearch.service.

  • Il existe un service d'indexation par type de stockage. Par exemple : BlockchainService, UserService, etc.

Aller plus loin dans le code

Cesium+ Pod s'appuie sur ElasticSearch en version 2.4. D'excellentes documentations sont présentes sur le web : https://www.elastic.co/guide/en/elasticsearch/reference/2.3/index.html.

Requêtes GET

En utilisant un navigateur, vous allez requêter .

• [GET-1] Visualisez un bloc quelconque (par exemple le premier #0): http://localhost:9200/g1-test/block/0

Etudiez ensuite le format du résultat :

{
  "_index":"g1-test",
  "_type":"block",
  "_id":"0",
  "_version":1,
  "found":true,
  "_source": {
    "number": 0,
    "...": "..."
  }
}

Observez qu'ElasticSeach a ajouté des informations : _index, _type, etc.

• [GET-2] Pour éviter d'avoir les informations additionnelles, ajoutez /_source : http://localhost:9200/g1-test/block/0/_source

Notez que le bloc courant est accessible en /g1-test/block/current

• [GET-3] Récupérer uniquement les champs hash, dividend et memberCount, pour le bloc #125 : http://localhost:9200/g1-test/block/125/_source?_source=number,hash,dividend,membersCount

Notez que vous pouvez avoir une meilleure présentation en ajoutant “&pretty” dans l'adresse;

• [GET-4] Les blocks qui référence une clef publique (recherche full text) : http://localhost:9200/g1-test/block/_search?q=8Fi1VSTbjkXguwThF4v2ZxC5whK7pwG2vcGTkPUPjPGU

Vous pouvez rechercher sur n'importe quelle chaine (recherche full-text), via cet option “q=”

Requêtes via HTTP POST

Les requetes de type POST permettent des filtrage beaucoup plus fins. C'est généralement ce type de requêtes qui est utilisées dans des logiciels clients. On peut par exemple ajouter une mise en surbrillance; requêter plusieurs index en une seule fois, etc.

Nous utiliserons curl pour requeter notre noeud ElasticSearch. Si vous ne l'avez pas encore installé, executer simplement (sous Linux) :

sudo apt-get install curl

Dans un terminal, exécuter les commandes suivantes :

• [POST-1] Récupérez les blocs ayant un dividende universel, en sélectionnant quelques champs uniquement (dividend, number, hash). :

curl -XGET 'http://localhost:9200/g1-test/block/_search?pretty' -d '{
"query": {
        "filtered" : {
            "filter": {
                "exists" : { "field" : "dividend" }
            }
        }
    },
    "_source": ["number", "dividend", "hash", "membersCount"],
   size: 10000
 }'

• [POST-2] Récupérez tous les blocs de #0 à #100 :

curl -XGET 'http://localhost:9200/g1-test/block/_search' -d '{
    "query": {
       "bool": {
           "should": {
                "range":{
                    "number":{
                        "lte":100
                    }
                }
            }
       }
    }
}'

Toute la doc pour aller plus loin dans les requetes

Voici la documentation pour aller plus loin :

• ElasticSearch official web site
• un bon tutoriel

Requêtes sur g1-test.data.duniter.fr

Nous allons requêter le noeud g1-test.data.duniter.fr déployé sur la monnaie Ğ1-test.

Note : Ce noeud est configuré AVEC la couche de sécurité Duniter4j. Les accès sur des URL non autorisés renverront une page vide (erreur HTTP 404).

curl -XPOST "https://g1-test.data.duniter.fr/page/record/_search?pretty" -d'
{
  "query": {        
        "bool":{
            "filter": [
                {"term":{
                        "issuer":"5ocqzyDMMWf1V8bsoNhWb1iNwax1e9M7VTUN6navs8of"
                    }
                }                
            ]
        }
  },
  "_source": ["title", "description", "time"],
  "from":0,
  "size":100
}'

curl -XPOST "https://g1.data.duniter.fr/page/comment/_search?pretty" -d'
{
  "query": {
        "bool":{
            "filter": [
                {"term":{
                        "record": "  ...   "   <-- mettre ICI la valeur [_id] de la page
                    }
                }
            ]
        }
  }
}'