Figure 1. un oiseau heureux pour faciliter toute installation frustrante
Les applications peuvent vivre douillettement dans CouchDB. Vous n’avez qu’à joindre des fichiers HTML et JavaScript à un design document et c’est bon ! Ajoutez-y des requêtes sur les vues et des fonctions d’affichage qui génèrent n’importe quel type de média à partir de vos documents JSON, et vous avez tout ce qu’il vous faut pour écrire des applications nécessitant uniquement CouchDB.
Si vous désirez installer et bidouiller votre propre version de Sofa pendant que vous lisez les chapitres suivants, sachez que nous utiliserons CouchApp pour télécharger le code source au fur et à mesure de notre exploration.
Nous sommes vraiment enjoués par la perspective de déployer des applications dans CouchDB, car, comme tout est dans un seul conteneur, cela encourage les utilisateurs à contrôler non plus uniquement les données, mais aussi le code source, ce qui permettra à un plus grand nombre de personnes de bâtir des applications web personnelles. Et quand l’heure de gloire vient pour l’application que vous bidouilliez dans votre temps libre, la capacité de CouchDB à passer à l’échelle ne fait pas de mal !
Dans CouchDB, un design document contient un mélange de langages de développement (HTML, JS, CSS) qui sont soit des pièces jointes, soit des attributs du design document. Idéalement, c’est votre environnement de développement qui se charge de tous ces détails. Plus encore, vous êtes habitué à la coloration syntaxique, à la vérification des instructions, à la documentation intégrée, aux macros, aux assistants, etc. À côté, l’édition de code JavaScript intégré dans une chaîne JSON ne fait pas très contemporaine.
Fort heureusement, nous nous sommes evertués à fournir une solution. Entrez dans l’univers de CouchApp. CouchApp vous permet de concevoir des applications CouchDB selon une approche de répertoires hiérarchisés : les éléments sont séparés, les fichiers .js sont clairement ordonnés, vos éléments statiques (CSS, images) ont leur place désignée, et la simplicité de la commande couchapp push vous évite d’avoir à sauvegarder votre application en tant que design document dans CouchDB. Besoin de modifier quelque chose ? Utilisez couchapp push et vous voilà parti !
Ce chapitre vous guide à travers les étapes d’installation de CouchApp. Vous y découvrirez quels autres assistants s’y trouvent pour faciliter votre vie. Une fois que nous aurons CouchApp, nous l’utiliserons pour installer et déployer Sofa sur une base de données CouchDB.
Le script Python de CouchApp tout comme le framework JavaScript que nous utiliserons a été réalisé lors de la conception de cette application d’exemple. Ils sont désormais utilisés par plusieurs applications et disposent d’une liste de diffusion, d’un wiki et d’une communauté de hackers. Il vous suffit de chercher « couchapp » sur l’Internet pour trouver les dernières informations à ce sujet. Nous remercions particulièrement Benoît Chesneau d’avoir conçu et de maintenir cette bibliothèque (et aussi pour contribuer au code Erlang de CouchDB ainsi qu’à des bibliothèques Python).
CouchApp est plus facile à installer en utilisant le script Python easy_install intégré au paquet setuptools. Si vous êtes sur Mac, easy_install devrait être disponible. Si vous êtes sur Debian (ou un dérivé comme Ubuntu) et que le paquet n’est pas installé, vous pouvez l’installer ainsi :
sudo apt-get install python-setuptools
Une fois que vous avez easy_install, installer CouchApp se fait ainsi :
sudo easy_install -U couchapp
Avec de la chance, cela fonctionne et vous êtes prêt à utiliser CouchApp. Si ce n’est pas le cas, lisez plus avant…
Le problème le plus couramment rencontré lors de l’installation de CouchApp est lié à d’anciennes versions des dépendances, tout particulièrement la version d’easy_install. Si vous obtenez une erreur lors de l’installation, la meilleure chose à faire est de tenter une mise à jour du paquet setuptools puis de réessayer, ce qui se fait ainsi :
sudo easy_install -U setuptools sudo easy_install -U couchapp
Si vous rencontrez d’autres problèmes, consultez le guide de dépannage de setuptools pour Python, ou consultez la liste de diffusion CouchApp.
Installer CouchApp avec easy_install devrait, comme on dit, être un jeu d’enfant. Si cela se déroule sans accroc, il devrait se charger de résoudre les dépendances et ajouter l’utilitaire couchapp dans le PATH du système pour que vous puissiez tout de suite exécuter :
couchapp --help
Nous utiliserons les commandes clone et push. clone récupère une application à partir d’une instance disponible sur le réseau et l’enregistre sur votre disque. Quant à push, il déploie une application CouchDB autonome depuis votre disque vers un serveur sur lequel vous avez des privilèges d’administration.
Il existe trois moyens de se procurer le code source de Sofa. Les trois sont similaires, c’est surtout une question de convenance personnelle et de ce que vous prévoyez de faire avec. Le moyen le plus simple est d’utiliser CouchApp pour cloner Sofa depuis une instance existante. Si vous n’avez pas installé CouchApp, vous pouvez lire le code source (mais pas l’installer et l’exécuter) en téléchargeant l’archive ZIP ou TAR. Si vous êtes du genre à bidouiller Sofa et vouliez rejoindre la communauté des développeurs, vous devriez exploiter le dépôt Git. Nous décrirons ces trois méthodes tour à tour. Avant cela, profitez de la Figure 1, un oiseau heureux pour faciliter toute installation frustrante.
Figure 1. un oiseau heureux pour faciliter toute installation frustrante
L’un des moyens les plus faciles d’obtenir le code source de Sofa est de le cloner directement depuis le blogue de J. Chris en utilisant la commande clone de CouchApp. Cela téléchargera les design documents et les stockera sur votre disque. La commande clone exploite une URL d’un design document qui peut être stocké dans n’importe quelle instance de CouchDB accessible par HTTP. Pour cloner la version de Sofa depuis le blogue de J. Chris, utilisez la commande suivante :
couchapp clone http://jchrisa.net/drl/_design/sofa
Vous devriez voir :
[INFO] Cloning sofa to ./sofa
Maintenant que vous avez Sofa sur votre disque, vous pouvez passer à la section Déployer Sofa pour effectuer quelques modifications avant de le mettre en place sur votre CouchDB.
Si vous comptez simplement lire attentivement le code source durant votre lecture, celui-ci est disponible sous la forme classique d’archives ZIP et TAR. Pour obtenir la version ZIP, utilisez votre navigateur pour vous rendre sur :http://github.com/couchapp/couchapp/zipball/master. Si vous préférez le format TAR, allez sur : http://github.com/couchapp/couchapp/tarball/master.
La version la plus à jour de Sofa sera toujours disponible sur son dépôt public. Si vous désirez utiliser les derniers développements et fournir des correctifs au dépôt, le meilleur moyen de le faire est avec Git et GitHub.
Git est un système de distribué de contrôle de version qui permet à des groupes de développeurs de conserver la trace des modifications apportées à un logiciel et de les échanger. Si vous connaissez Git, vous n’aurez aucun problème à l’utiliser pour travailler avec Sofa. En revanche, si vous n’avez jamais utilisé Git par le passé, sachez que l’apprentissage est un peu long, donc, selon votre tolérance vis-à-vis des nouveaux logiciels, vous préférerez peut-être garder ça pour un autre jour – ou tout simplement plonger dedans la tête la première ! Pour trouver plus d’informations sur Git et comment l’installer, référez-vous à la page d’accueil officielle de Git. Pour des trucs et astuces ou de l’aide, référez-vous aux guides GitHub.
Pour obtenir Sofa (et tout l’historique de développement) avec Git, utilisez la commande suivante :
git clone git://github.com/jchris/sofa.git
Maintenant que vous avez obtenu les sources, regardons-les !
Une fois que vous avez obtenu le code source par l’une des méthodes précitées, vous avez de quoi travailler sur votre disque. Le texte ci-dessous est obtenu par la commande tree sur le répertoire de Sofa pour lister son contenu. Certaines sections sont annotées pour faire ressortir ce qui a trait aux design documents.
sofa/ |-- README.md |-- THANKS.txt
L’arbre contient des fichiers qui ne sont pas nécessaires à l’application, telle que les fichiers README et THANKS.
|-- _attachments | |-- LICENSE.txt | |-- account.html | |-- blog.js | |-- jquery.scrollTo.js | |-- md5.js | |-- screen.css | |-- showdown-licenese.txt | |-- showdown.js | |-- tests.js | `-- textile.js
Le répertoire _attachments abrite les pièces jointes binaires au design document. CouchDB fournit ces pièces jointes directement (plutôt que de les intégrer dans une enveloppe JSON), c’est dont là que l’on stocke les fichiers JavaScript, CSS et HTML auxquels le navigateur accèdera directement.
C’est en réalisant votre première édition du code source que vous comprendrez combien il est facile de modifier l’application.
|-- blog.json
Le fichier blog.json contient le JSON nécessaire à la configuration d’une installation de Sofa. Pour le moment, il définit une seule valeur : le titre du blogue. Vous devriez ouvrir immédiatement ce fichier et personnaliser le champ titre – vous ne voulez probablement pas appeler votre blogue « Daytime Running Lights », donc remplacez-le par quelque chose d’amusant !
Vous pourriez ajouter d’autres paramètres du blogue dans ce fichier, comme le nombre d’éléments à afficher par page et une URL pour une page « à propos de l’auteur ». Effectuer ces changements sera facile quand vous aurez lu les chapitres suivants.
|-- couchapp.json
Nous verrons par la suite que couchapp affiche un lien vers la page d’accueil de Sofa quand la commande couchapp push est exécutée. Cela fonctionne très simplement : CouchApp recherche le champ JSON du design document à l’adresse design_doc.couchapp.index. S’il le trouve, il ajoute son contenu à l’URL du design document pour construire l’URL du blogue. Il n’y a pas d’index CouchApp de spécifié, mais le design document a une pièce jointe appelée index.html, ce qui en fait la page d’accueil. Dans le cas de Sofa, nous utilisons la valeur d’index pour orienter vers une liste des articles récents.
|-- helpers | `-- md5.js
Le répertoire helpers résulte d’un choix arbitraire. CouchApp y mettra tous les fichiers et répertoires du design document. Dans notre cas, le code source de md5.js est encodé en JSON et stocke l’élément design_document.helpers.md5.
|-- lists | `-- index.js
Le répertoire lists abrite une fonction JavaScript qui sera exécutée pour générer les enregistrements selon des index HTML et Atom. Vous pourriez y ajouter de nouvelles fonctions en créant de nouveaux fichiers. Les listes sont détaillées dans le Chapitre 14, lister les articles d’un blogue.
|-- shows | |-- edit.js | `-- post.js
Le répertoire shows abrite les fonctions que CouchDB utilise pour générer les vues HTML des articles du blogue. Il y a deux vues : l’une pour lire les articles et l’autre pour les éditer. Nous reviendrons sur ces fonctions dans les prochains chapitres.
|-- templates | |-- edit.html | |-- index | | |-- head.html | | |-- row.html | | `-- tail.html | `-- post.html
Le répertoire templates se différencie des répertoires lists, shows et views, car son contenu n’est pas directement exécuté par CouchDB du côté serveur. En fait, les patrons sont injectés dans le corps des fonctions lists et shows par CouchApp lorsque l’application est envoyée au serveur. Ces macros sont détaillées dans le Chapitre 12, Stockage des documents. Ce qu’il faut retenir est que ce répertoire pourrait s’appeler d’une tout autre manière : il n’a pas de fonction prédéterminée au sein d’un design document ; c’est simplement un endroit choisi pour regrouper et modifier vos patrons.
|-- validate_doc_update.js
Ce fichier contient la fonction JavaScript de validation utilisée par Sofa pour garantir que seul le propriétaire du blogue peut y créer des articles et que les commentaires sont en bonne et due forme. Cette fonction est détaillée dans le Chapitre 12, Stockage des documents.
|-- vendor | `-- couchapp | |-- README.md | |-- _attachments | | `-- jquery.couchapp.js | |-- couchapp.js | |-- date.js | |-- path.js | `-- template.js
Le répertoire vendor abrite du code qui est géré indépendamment de l’application elle-même. Dans le cas de Sofa, le seul paquet externe utilisé est couchapp, lequel contient le code JavaScript qui détermine la manière dont le lien est fait entre les URL de list et de show, ou encore la manière dont sont exploités les patrons.
Pendant l’opération couchapp push, les fichiers se trouvant dans le chemin vendor/**/_attachments/* sont envoyés au serveur en tant que pièces jointes du design document. Dans notre cas, le fichier jquery.couchapp.js deviendra une pièce jointe nommée couchapp/jquery.couchapp.js. Ainsi, les paquets externes peuvent inclure des fichiers qui ont le même nom.
`-- views
|-- comments
| |-- map.js
| `-- reduce.js
|-- recent-posts
| `-- map.js
`-- tags
|-- map.js
`-- reduce.js
Le répertoire views abrite la définition des vues MapReduce. Chaque vue a son propre répertoire et contient deux fichiers : l’un pour la fonction de subdivision (map), l’autre pour la fonction d’agrégation (reduce).
Le code source est désormais sur votre disque et vous avez pu faire quelques retouches au fichier blog.json. Il est grand temps de déployer le blogue sur une instance locale de CouchDB. La commande push est simple et devrait réussir du premier coup. Toutefois, deux étapes supplémentaires sont nécessaires pour créer un compte d’administration sur votre CouchDB pour permettre vos déploiements avec CouchApp. À la fin de chapitre, vous aurez un Sofa opérationnel.
Chaque fois que vous modifiez le Sofa qui se trouve sur votre disque, et que vous voulez observer les changements dans votre navigateur, exécutez la commande suivante :
couchapp push . sofa
Cela a pour effet de déployer le code sur CouchDB. Vous devriez voir le résultat suivant :
[INFO] Pushing CouchApp in /Users/jchris/sofa to design doc: http://127.0.0.1:5984/sofa/_design/sofa [INFO] Visit your CouchApp here: http://127.0.0.1:5984/sofa/_design/sofa/_list/index/recent-posts?descending= true&limit=5
Si vous rencontrez une erreur, assurez-vous que votre instance CouchDB est disponible en forgeant une requête HTTP :
curl http://127.0.0.1:5984
Vous devriez recevoir :
{"couchdb":"Welcome","version":"0.10.1"}
Si CouchDB n’est pas démarré, référez-vous au Chapitre 3, Premiers pas et suivez les instructions du « hello world ».
Si CouchDB était disponible, alors la commande couchapp push devrait vous avoir invité à visiter l’URL de la page d’accueil. Vous y rendre devrait vous afficher quelque chose ressemblant à la Figure 2, Page d’accueil vide.
Figure 2. Page d’accueil vide
Ce n’est pas fini ! Nous avons encore quelques étapes à franchir avant d’avoir une instance opérationnelle de Sofa.
Sofa est une application mono-utilisateur. Vous, l’auteur, êtes l’administrateur et la seule personne qui puisse ajouter et éditer des articles. Pour vous assurer qu’autrui ne viendra pas semer le bazar, vous devez créer un compte d’administrateur dans CouchDB. C’est assez simple. Trouvez le fichier local.ini et éditez-le avec votre outil préféré (par défaut, ce fichier se trouve dans /usr/local/etc/couchdb/local.ini). Si ce n’est déjà fait, décommentez la section [admins]. Ensuite, ajoutez une ligne sous la section [admins] avec votre nom d’utilisateur préféré ainsi que votre mot de passe :
[admins] jchris = secretpass
Maintenant que votre fichier de configuration local.ini est prêt, vous devez redémarrer CouchDB pour que la modification soit prise en compte. Selon la manière dont vous avez démarré CouchDB, il y a plusieurs moyens de le redémarrer. Si vous l’avez démarré en mode console, vous pouvez presser CTRL+C puis relancer la commande antérieure ; c’est la moyen le plus simple.
Si vous n’aimez pas laisser traîner vos mots de passe dans des fichiers textes, ne vous inquiétez pas. Quand CouchDB démarre et lit le fichier, il chiffre de manière non réversible votre mot de passe, comme ceci :
[admins] jchris = -hashed-207b1b4f8434dc604206c2c0c2aa3aae61568d6c,96406178007181395cb72cb4e8f2e66e
CouchDB vous demandera désormais vos identifiants quand vous tentez de créer une base de données ou que vous voulez modifier un document – c’est tout à fait ce que vous vouliez protéger.
Maintenant que les identifiants administrateur sont définis, nous devons les fournir à couchapp push. Essayons :
couchapp push . http://jchris:secretpass@localhost:5984/sofa
Assurez-vous de remplacer jchris et secretpass par vos propres identifiants, ou vous obtiendrez une erreur « permission denied ». Si tout s’est bien passé, nous avons tout configuré et vous devriez pouvoir utiliser votre blogue.
Désormais, nous sommes techniquement parés à avancer. Toutefois, vous serez bien plus heureux après avoir modifié le fichier .couchapprc comme le décrit la section suivante.
Si vous ne voulez pas avoir à entrer l’URL complète (de surcroît avec les identifiants) de votre base de données à chaque fois que vous effectuez un envoi, vous pouvez utiliser le fichier .couchapprc pour stocker les informations de déploiement. Le contenu de ce fichier n’est pas envoyé au serveur, donc c’est un bon endroit pour conserver vos identifiants lors de l’envoi vers des serveurs sécurisés.
Le fichier .couchapprc se trouve à la racine du répertoire contenant votre application. Vous devriez regarder s’il existe dans /chemin/vers/le/répertoire/de/sofa/.couchapprc ; à défaut, créez-le. Les fichiers cachés (commençant par un point) sont souvent ignorés par les listages de répertoires. Recourez donc aux moyens que votre système d’exploitation met à votre disposition pour les afficher. Dans un terminal standard, vous pouvez normalement obtenir cette liste avec la commande ls -a, laquelle montrera tous les fichiers cachés aux côtés des fichiers normaux.
{
"env": {
"default": {
"db": "http://jchris:secretpass@localhost:5984/sofa"
},
"staging": {
"db": "http://jchris:secretpass@jchrisa.net:5984/sofa-staging"
},
"drl": {
"db": "http://jchris:secretpass@jchrisa.net/drl"
}
}
}
Une fois ce fichier rempli, vous pouvez envoyer votre CouchApp à l’aide de la commande couchapp push, ce qui l’enverra vers la base de données par défaut. CouchApp est aussi capable de gérer des environnements alternatifs. Aussi, pour envoyer votre application sur une base de données de développement, vous pouvez utiliser la commande couchapp push dev. Notre expérience fait valoir l’intérêt qu’il y a à prendre le temps de définir correctement ce fichier. Un autre avantage est que votre mot de passe n’est plus affiché à l’écran.