Créer ses propres projets avec BOINC
(installation, configuration, compilation et mise à jour de projets BOINC
sous Linux et sous Windows)

 

Informations générales

Cette documentation est sans doute utile pour tous ceux qui ont de l'intérêt à créer leurs propres projets BOINC, et sans doute inutile pour tous ceux qui ne souhaitent qu'utiliser BOINC en tant que simple client, pour lancer les projets existants. Il faut quelques connaissances de base en système (commandes sous Linux notamment) et des connaissances en programmation. Il faut évidemment un serveur connecté 24h/24 à Internet.

Avant de développer un projet BOINC, on doit se demander si le projet développer va être utile et intéresser la communauté des utilisateurs et le grand public. Des critères permettent de définir un bon projet BOINC. Il faut notamment que le projet soit médiatique, qu'il demande une puissance de calcul importante et que l'institution qui le diffuse à l'air sérieuse. Ceci est évidemment laissé à l'appréciation de chacun. On peut voir de plus amples informations à ce sujet [ici].

Cependant, il n'y a pas besoin d'être une institution importante pour inventer et proposer ses propres idées de projet de calcul distribué. Il n'y a d'ailleurs pas que des ressources de calcul à la disposition des projets mais aussi des ressources de disque. D'ailleurs en général un utilisateur de BOINC a plus de disque à mettre à disposition que de temps CPU...

Il est donc possible de créer ses propres projets. On peut donc librement mettre en place des projets qui seront totalement indépendants du site officiel de BOINC, des autres projets, et du code en cours de développement. Toutes les parties sont installées et utilisées localement sur une (votre) machine dédiée.

Avant de se lancer, une simple question : faut-il du temps pour se lancer dans l'aventure ? Je dirais OUI ! Cette doc est très très longue (et complexe) et risque d'en décourager certains. Il faut du temps à la fois pour terminer ce tutorial (2-3 matinées sont nécessaires), mais aussi ensuite pour maintenir et corriger les bugs rapportés par vos différents clients (qq heures par semaine)... Et ceci quelle que soit la configuration et le système sur lesquels ont été rencontrés ces bugs... Il faut donc tout de même quelques connaissances sur plusieurs plates-formes qui dépendront de la complexité du projet en question. Ou alors il faut s'associer en équipe...

Chapitre 0 - Vue d'ensemble du fonctionnement de BOINC

[http://www.chessbrain.net/LFBOF2005/images/boinc.gif]

Le schéma présente l'architecture d'un projet BOINC. Elle a l'air complexe comme ça mais en réalité, il faut simplement :

Cette doc est divisée en 4 chapitres :

  1. installation d'une machine sous Linux et de tous les outils nécessaires pour pouvoir ensuite accueillir la plate-forme BOINC
  2. installation de BOINC en lui-même
  3. création et configuration d'un nouveau projet
  4. gestion et mise à jour d'un projet existant

Ce que cette doc décrit :

Ce que cette doc ne décrit pas :

Il est intéressant de lire la doc officielle [ici], au moins les premiers liens qui donnent la définition de quelques termes importants (project, application, workunit, result). Par contre, la lecture des pages concernant l'API n'est pas utile tout de suite. Une workunit (unité de travail) est la partie de calcul qu'un client va réaliser à un instant donné. Une application est un programme compilé pour un environnement donné (par exemple "Windows-Intel", "Linux-SPARC", etc) calculant des workunits. Un projet est l'ensemble de toutes les applications pour tous les environnements cibles, ainsi que des scripts de mise à jour, du site Web principal, ...

 

Chapitre 1 : installation des outils nécessaires

On ne peut malheureusement pas sauter cette étape, et seule une machine Linux peut pour l'instant être utilisée. Cependant ces outils sont très standards (serveur Web Apache, librairies OpenGL, ...). J'indiquerais cependant les outils qui n'ont pas forcément besoin d'être installés (par exemple Apache SSL).

Il faut tout d'abord une machine contenant le système d'exploitation Linux. Choisissez Debian (mon cas), Redhat ou n'importe quelle autre distribution. Le but ici n'est pas de décrire une telle installation, et d'ailleurs il existe de nombreuses documentations sur Internet à ce sujet. Généralement on télécharge une ISO sur Internet, on la grave, on reboot dessus, et on installe Linux pas à pas.

Installation des outils

Ensuite il faut installer les différents outils nécessaires (voir [ici]) pour la compilation de BOINC et des futurs projets. Selon la distribution de Linux, leur installation se fait en ligne de commande (ex: apt-get sous Debian, yum pour CentOS, ...) ou en utilisant le gestionnaire de packages graphique du système. Il faut évidemment être root pour cela.

Il faut les outils avec au moins les versions suivantes :

Taper par exemple (sur une Debian, adapter pour les autres distributions) :

# Outils de compilation et de développement classiques
apt-get install make m4 libtool pkg-config autoconf automake-1.9 gcc-4.1 cvs crontab
# Langage de programmation Python
apt-get install python2.5 python-mysql python-xml
# Base de données MySQL
apt-get install mysql-server mysql-client libmysqlclient14-dev
# Outils supplémentaires MySQL
apt-get install mysql-base mysql-common mysql-dev mysql-devel
# Serveur Web Apache
apt-get install apache libapache-mod-ssl libapache-mod-php4
apt-get install apache-ssl
# Cryptage des échanges avec SSL (pour la communication des futurs clients)
apt-get install openssl
# Permet l'échange de données par le Web
apt-get install libcurl-dev


Attention, il est possible que sur votre configuration, certains de ces outils existent déjà. Vous pouvez les mettre à jour ou les laisser tels quels. Certains packages ne pourront sans doute pas être installés si d'autres outils ne sont pas à jour : accepter les options de mise à jour proposées. Certains packages demanderont de préciser la version voulue : il faudra taper "apt-get install gcc-4.1" plutôt que "apt-get install gcc" par exemple).

Les lignes en bleues sont les outils qui ne sont peut être pas nécessaires, mais qui peuvent provoquer des refus de compilation plus tard. Par exemple, je me suis rendu compte plus tard que le script "mysql_config" n'était pas présent sur ma machine, il se trouve dans le package libmysqlclient. Sur Debian, il existe un moteur de recherche pour trouver les paquets à installer en cas d'un outil manquant [ici]. Si vous ne pouvez pas compiler BOINC, regardez si les messages produits ne sont pas en rapport avec ces packages et installez-les. Par exemple le package "apache-ssl" sert à mettre en place un serveur Web Apache sur le port SSL (443) (cela permet d'avoir accès à des URL du type "https://votre.site.com/"). Si vous avez déjà un autre serveur Apache, il n'est pas obligatoire d'en installer un nouveau à côté.

Je n'ai pas rencontré de problèmes particuliers lors de l'installation de ces packages, à partir du moment où j'utilisais l'outil de Debian, et que je n'installais pas ces packages à la main, c'est à dire en les téléchargeant et en les compilant moi-même.

Configuration des outils

Ne pas oublier que pour prendre en compte certains paramètres, il faut parfois redémarrer le serveur Apache (généralement avec la commande "apachectl restart" ou "/etc/init.d/apache restart"). Les logs d'Apache sont très très utiles pour trouver les erreurs et comment les corriger (voir par exemple /var/log/apache/access.log et /var/log/apache/error.log).

Chapitre 2: installation et compilation de BOINC

Je parle ici de la version stable de BOINC, aujourd'hui (1er Sept. 2006) la version "5.4.11". J'espère que tout ne va pas changer lorsqu'ils feront passer une version en développement en version stable !

Récupération du code source de BOINC

La première étape (décrite [ici]) est la récupération du code source de BOINC. Les étapes suivantes peuvent se faire avec le compte d'un simple utilisateur, c'est ce que je conseille de faire.

Sous root :

adduser boinc

Compléter les informations demandées, puis pour se retrouver dans le répertoire HOME :

su boinc
cd

On récupère ensuite la dernière version de BOINC :

cvs -d :pserver:anonymous:@alien.ssl.berkeley.edu:/home/cvs/cvsroot checkout -r stable boinc

Ceci peut prendre quelques minutes, cela dépend de la connexion internet. Pour ceux qui veulent voir le code source, comparer différentes versions, etc, il y a le lien CVSWeb.

Compilation du code source de BOINC

La seconde étape est la compilation de tout le code source. Plus de détails [ici], [ici] et [ici].

cd boinc
./_autosetup
./configure --disable-client

Les commandes autosetup et configure prennent du temps et c'est normal. L'option "--disable-client" permet de ne construire que le serveur (par défaut le client est aussi compilé). Il faut remonter pour voir les messages d'erreurs éventuels. Normalement le script se plaint de l'absence des librairies graphiques (JPEG, OpenGL, Glut et wxWidgets). La plupart des messages d'erreurs est dûe à des outils ayant une version trop vieille. Dans ce cas, récupérer le nom de l'outil fautif, lancer "outil --help" ou "outil --version" ou "outil -V" et comparer la version avec la liste indiquée. Si la version est trop vieille, désinstaller et ré-installer l'outil en spécifiant la version (ex: "apt-get install automake1.9") ou en allant le télécharger et l'installer manuellement depuis le site officiel.

Ensuite, on peut lancer différents tests. Ils sont décrits [ici]. Par exemple, pour tester la base MySQL :

python ./test/test_sanity.py

S'il y a un problème, c'est que MySQL n'a pas été correctement configuré. Eventuellement, il faut créer un utilisateur qui possède l'accès à la base en local.

Si les librairies graphiques ont été installées, on peut taper "make" directement. Sinon il faut désactiver à la main la compilation des démonstrations graphiques, qui peuvent bloquer ou arrêter la compilation. Editer le fichier "~/boinc/Makefile", et chercher la première ligne contenant "DIST_SUBDIRS". Effacer les références aux dossiers "apps", "clientgui" et "sea", de telle sorte que la ligne devienne : "DIST_SUBDIRS = m4 api lib zip db test py sched tools client". Chercher aussi la première ligne contenant "SERVER_SUBDIRS", et la remplacer par : "SERVER_SUBDIRS = db test py sched tools".

make
(sous root) make install

Voici par exemple les erreurs obtenues si OpenGL n'est pas installé :

upper_case.C: In function `bool app_render(int, int, double)':
upper_case.C:256: error: `GL_COLOR_BUFFER_BIT' undeclared (first use this function)
upper_case.C:256: error: (Each undeclared identifier is reported only once for each function it appears in.)
upper_case.C:256: error: `GL_DEPTH_BUFFER_BIT' undeclared (first use this function)
...

Chapitre 3 : Création et configuration d'un nouveau projet

Il est temps de créer un nouveau projet. Je décris ici le projet "Hello" un simple programme qui attend un peu puis écrit une ligne dans un fichier qui est ensuite envoyé au serveur. Il est possible d'utiliser ce programme ensuite pour des projets plus gros. D'autres projets d'exemple sont disponibles [ici], [ici] et [ici] (voir le CVS et le module "boinc_samples").

Création du dossier du projet (make_project)

Tout d'abord il faut créer le dossier contenant tous les scripts et les pages web spécifique à votre nouveau projet. Il faut aussi créer la base MySQL. Heureusement, il y a déjà des scripts prévus pour faire le tout en une seule étape. Exécuter :

~/boinc/tools/make_project --url_base http://votre.site.com/boinc/ --delete_prev_inst --drop_db_first --db_name BOINC_HELLO --db_user boinc_user --db_passwd boinc_pass hello

L'option "--url_base" doit indiquer l'url de votre site (par défaut il récupère le reverse de l'adresse IP, ce qui ne marche pas pour les DNS dynamiques). Le dossier "boinc" ne doit pas exister dans la racine du site Web. Les options "--delete_prev_inst" et "--drop_db_first" ne sont utiles que si on souhaite supprimer toute occurrence du projet précédent ayant le même nom. Les options "--db_name", "--db_user" et "--db_passwd" indiquent le nom de la base de données, l'utilisateur et le mot de passe pour y accéder. Il est conseillé de créer auparavant un utilisateur spécifique à BOINC (exemple: boinc_user, rien à voir avec l'utilisateur "boinc" du système) et de sauvegarder la base existante (mysql-dump). PhpMyAdmin permet de faire tout cela simplement. Le dernier argument est tout simplement le nom du projet (ici "hello"). Lancer la commande, et répondre "Y" partout, notamment pour la création des clés de cryptage. Plus de détails sont disponibles [ici].

Résultat : un dossier ~/projects/hello est créé. Le dossier "projects" contient tous les projets BOINC (ils seront indépendants entre eux si vous en créer plusieurs). Le dossier "hello" contient divers fichiers nécessaires à la gestion du projet et du site web.

Configuration des outils (serveur Web et crontab)

Le projet n'est pas complètement installé. Il faut encore :

Résultat : un site Web est disponible sur l'adresse : http://votre.site.com/boinc/hello/. Chez moi le logo du flux RSS n'est pas disponible, mais ce n'est pas très important. Il doit être possible de créer un nouveau compte avec le menu "Créer le compte" sur votre site Web.

Ajout des environnements (xadd)

Ensuite il faut ajouter les noms (et pour l'instant uniquement les noms) des futures applications (programme compilé pour l'un ou l'autre des environnements cibles) à la base de données. C'est lors de cette étape qu'on prévoit pour quels environnements les applications seront développées. Un environnement est à la fois la réunion d'un système d'exploitation (Windows, Linux, Mac) et d'un processeur (x86, AMD, ...). Pour 3 systèmes et 2 processeurs, il y a 6 applications différentes. Il faut donc compiler les applications autant de fois que nécessaire. Créer un fichier "~/projects/hello/project.xml" contenant (par exemple) :

<boinc>
    <platform>
        <name>i686-pc-linux-gnu</name>
        <user_friendly_name>Linux/x86</user_friendly_name>
    </platform>
    <platform>
        <name>windows_intelx86</name>
        <user_friendly_name>Windows/x86</user_friendly_name>
	 </platform>
	 <app>
        <name>hello</name>
        <user_friendly_name>The Hello Test App</user_friendly_name>
    </app>
</boinc>

Explications : il y a autant de sections <platform> que d'environnements différents composés d'un système et d'un processeur (plus de détails [ici]). Lancer ensuite la commande "~/projects/hello/bin/xadd".

Compilation des applications

Il est maintenant temps de programmer les applications elles-mêmes. Une fois programmée, une application doit être compilée sur toutes les plates-formes que les futurs utilisateurs sont susceptibles de posséder. Généralement il y a des applications pour Windows, Linux et Mac.

Pour compiler Hello sous Windows, voir la page Windows, puis lire "Ajout des versions d'application".

Pour compiler Hello sous Linux, continuer à suivre ce tutorial. Plus de documentation est disponible [ici] et [ici].

Commencer par télécharger le code source du projet Hello. Dans la pratique, il faut utiliser l'API BOINC décrite [ici]. Les règles de base sont les suivantes :

Ici nous allons directement télécharger Hello pour Linux, disponible (version 5.05) [ici] ou [ici] (copie locale).

cd ~/projects/hello/apps
wget http://www.spy-hill.net/pub/myers/src/boinc/hello-5.05.tar.gz
tar xvfz hello-5.05.tar.gz
mv hello.d hello
cd hello

Editer le fichier "hello.C". C'est l'unique fichier de code source. Remplacer :

#include "diagnostics.h"
#include "boinc_api.h"
#include "filesys.h"

Par

#include <BOINC/diagnostics.h>
#include <BOINC/boinc_api.h>
#include <BOINC/filesys.h>

Puis taper la commande "make".

Résultat : le projet est compilé et l'exécutable "hello_5.05_i686-pc-linux-gnu" est créé. On peut tester directement l'application sous Linux, il suffit de l'exécuter en tapant son nom (noter que pour éviter les erreurs de l'application, 'il faut auparavant créer des fichiers "boinc_finish_called", "init_data.xml" et "out.txt" vides dans le même dossier).

Ajout des versions d'application (update_versions)

Maintenant le nom des applications (Windows ou Linux) se trouve dans la base (commande xadd vue précédemment), et les applications sont compilées et doivent être placées dans le dossier ~/projects/hello/apps/ (qu'elles proviennent de Windows ou Linux). Il reste à ajouter les applications elles-mêmes au projet. Cette étape peut servir soit la première fois, pour ajouter les premières applications dans le projet, soit ensuite pour modifier (mettre à jour) la version d'une application par une version plus récente. L'application doit être dans le dossier "~/projects/hello/apps/hello/" et porter un nom de la forme NOM_VERSION_SYSTEME_PLATEFORME. La partie "SYSTEME_PLATEFORME" doit être strictement la même que celle déjà enregistrée dans le fichier "~/projects/hello/project.xml".

cd ~/projects/hello
bin/update_versions

Répondre "Y" aux demandes de création de signatures. Ces signatures servent à authentifier les fichiers téléchargés par le client, pour qu'il soit sûr qu'il provient bien de votre serveur et qu'ils n'ont pas été modifiés en cours de route. Redémarrer ensuite le démon BOINC :

bin/stop && bin/start

Résultat : votre site "http://votre.site.com/boinc/hello/apps.php" affiche les nouvelles applications. Plus de doc [ici] et [ici].

Création d'unités de travail / workunits (create_work)

Le dur labeur touche enfin à sa fin ! Il reste à créer des unités de travail pour que vos clients puissent travailler ! Pour cela, il faut indiquer à BOINC quelle est la forme de ce qu'on donne en entrée aux unités de travail et de ce qu'on récupère en sortie, de telle sorte qu'il puisse correctement gérer les upload/download de résultats à partir du serveur. La forme est décrite en utilisant des templates. Commencez par copier les templates prédéfinis dans le dossier "template" du projet :

cp ~/projects/hello/apps/hello/hello_wu.xml ~/projects/hello/templates/
cp ~/projects/hello/apps/hello/hello_re.xml ~/projects/hello/templates/

Ces templates sont décrits [ici]. Basiquement, le template "hello_wu.xml" décrit les paramètres généraux des unités de travail (nombre d'unités à toujours avoir disponible, délai accordé pour le calcul, ...). Le template "hello_re.xml" décrit les paramètres d'entrée du programme et le nom du fichier de sortie (ici ce fichier est nommé "out.txt"). Le fichier de sortie doit être créé par l'application et sera uploadé ensuite sur le serveur comme fichier de résultat. Ces templates sont très simples, il est possible de les compliquer pour d'autres utilisations. Notamment certaines commandes, lancées ici par des scripts en ligne de commande, peuvent être utilisées par des programmes compilés, en utilisant une sorte d'API.

cd ~/projects/hello
bin/create_work -appname hello -wu_name hello-wu -wu_template templates/hello_wu.xml -result_template templates/hello_re.xml

Les arguments de "create_work" indiquent simplement le chemin des templates et le nom de l'application. Il y a d'autres détails [ici].

Dernières configurations

Je conseille d'aller faire un tour dans le fichier "~/projects/hello/config.xml" pour régler certains paramètres :

Actuellement, le calcul des crédits par BOINC se fait automatiquement en évaluant le temps passé par le système pour calculer une unité de travail moyenne. Les crédits sont accordés par le "simple_trivial_validator", un valideur simple mais qui fonctionne bien par défaut.

Résultats :

Si rien ne se passe, il faut voir dans les logs d'Apache s'il n'y a pas de problème avec l'URL (ce que le client fait est visible dans les logs).

 

Chapitre 4 : Gestion et mise à jour d'un projet existant

Voici la marche à suivre pour supprimer l'ancienne version d'une application et ajouter la nouvelle la nouvelle version. Tout se passe dans le dossier du projet, sur le serveur Linux (par exemple, ~/projects/hello/).

Si l'application ne nécessite qu'un seul fichier, lui donner un nom de la forme :

Si l'application a besoin d'autres fichiers (des DLLs sous Windows par exemple), créer un dossier de la forme :

Sur le serveur Linux, déplacer les vieilles applications ou les supprimer (en cas de mise à jour forcée), puis lancer :

./bin/update_versions && ./bin/stop && ./bin/start

La page du projet (par exemple, "http://votre.site.com/boinc/hello/apps.php") devrait indiquer la présence des nouvelles versions. Les commandes stop et start ne sont nécessaires que si l'on doit impérativement refuser de nouvelles unités calculées avec la précédente version.

La gestion du projet (du point de vue administrateur) se fait avec la page Web qui se trouve sur votre serveur :

http://votre.site.com/boinc/hello_ops/

Si la page est inaccessible, vérifier le chemin d'alias dans le fichier httpd.conf, et vérifier si le répertoire contenant les pages en PHP est bien présent dans "~/projects/hello/html/ops". Si la page est accessible, mais non protégée par un mot de passe (ce qui est dangereux), exécuter :

cd ~/projects/hello/html/ops
htpasswd -c .htpasswd boinc_adm (mettre un mot de passe)

Puis éditer un fichier .htaccess (dans le même dossier) et y placer :

AuthUserFile /home/uboinc/projects/hello/html/ops/.htpasswd
AuthGroupFile /dev/null
AuthName "Accès protégé"
AuthType Basic
<LIMIT GET POST>
Require valid-user
</LIMIT>

Liens intéressants

J'ai regroupé ici tous les liens qui peuvent intéresser ceux qui veulent développer de nouveaux projets avec BOINC.

Malheureusement beaucoup de liens sont en anglais... Il n'y a pas beaucoup de doc en français pour nous, pauvres francophones... Néanmoins toutes ces documentations m'ont permis, avec du temps, d'arriver à monter mon propre petit projet BOINC, donc si vous cherchez une information manquante, elle se trouve sans doute dans les liens ci-dessous.

Documentations sur des étapes spécifiques lors de la création d'un nouveau projet :

Listes et statistiques complètes de projets BOINC :

Méthodes de construction de projets BOINC. Ces méthodes sont incomplètes, mais couvrent le sujet de bout en bout et peuvent aider car le point qui bloque se trouve peut être dans l'une d'elles.

Concerne le projet (non-BOINC) de l'Université de Standford "Folding@Home" et l'intégration en tant que projet BOINC.

Autres aides :

Divers, insolite :