C'est un brouillon pour installer daCode, pas à pas...

Ce document propose de mettre en oeuvre daCode en
explorant en détail chaque étape.


Chapitre 1 : installer daCode sur localhost


daCode est une application Web basée sur un langage de scripts (PHP)
et une base de données (MySQL ou PostgreSQL, peut-6tre d'autres
ultérieurement).

Les applications Web sont un peu particulières à installer.
Il faut récupérer un package, mettre en place des scripts
et faire une initialisation de la base de données. C'est
une logique assez différente d'un logiciel `normal', mais
en utilisant le bon outil, c'est très facile.

Le bon outil, c'est CVS.

CVS permet de synchroniser les fichiers avec la base centrale,
ce qui vous permettra de mettre à jour votre daCode de
manière transparente et aussi de participer au développement.

daCode bouge beaucoup. Ce doit être assez général pour les
applications Web. Vous avez intérêt de prévoir des
mises à jour fréquentes. Se lancer dans CVS est un bon
investissement.

Avant de commencer à installer daCode, on va préparer un petit nid
douillet pour daCode et vérifier que tout est en place.
On peut créer un utilisateur spécifique `dacode' si
on veut bien séparer ces fichiers du reste. C'est
pratique pour les sauvegardes et le nettoyage. Mais
si vous avez un login perso, il est tout aussi faisable
de l'utiliser. Moi j'utilise un login perso, mais pour
rediger ce papier j'ai pris l'autre methode:
	# adduser dacode
	# su - dacode
	$ passwd
Vous utiliserez ce login pour faire des modifs sur daCode :
soit des mises à jours, soit du développement.


Maintenant, on va vérifier que votre config est bonne.

Chez moi, je procède ainsi:
	$ mysql -V
	mysql  Ver 9.38 Distrib 3.22.32, for pc-linux-gnu (i686)
	$ cvs -v
	Concurrent Versions System (CVS) 1.10.8 (client/server)
	$ mkdir public_html
	$ echo "<? phpinfo(); ?>" > public_html/test.php3

	$ netscape http://localhost/~dacode/test.php3

Si Netscape n'affiche rien, commencez par soupconner un
problème de droits d'accès et corrigez-le avec `chmod o+rx'.
Apache va avoir besoin de lire vos fichiers et de parcourir
vos répertoires:
	$ ls -l ~dacode | grep public_html     ### ca c'est OK
	drwxr-xr-x    2 dacode   dacode       4096 jan  3 22:50 public_html/
	$ ls -l ~dacode/.. | grep dacode       ### ca c'est pas bon
	drwx------    8 dacode   dacode       4096 jan  3 22:52 dacode/
	$ chmod o+rx ~dacode 
	$ ls -l ~dacode/.. | grep dacode       ### là c'est mieux
	drwx---r-x    8 dacode   dacode       4096 jan  3 22:52 dacode/

Si Netscape ne marche pas mieux, maintenant, vous avez un pépin avec
apache ou PHP. Ouille :(
Si ca marche, regardez dans les infos la version de PHP
et la présence des Extensions MySQL et Apache. On pourra en avoir
besoin plus tard s'il y a des problèmes.
	Chez moi : php 3.0.16 , mysql 3.22.32 , apache 1.3.12
	config Mandrake 7.1 de base. Ca existe les vieilles Mandrake! :p

Faites chauffer le modem, on va récuperer daCode.
Choisissez votre stratégie. Si c'est juste pour voir la tête
que ca donne, passez par le `snapshot quotidien' qui est construit
toutes les nuits. Si vous pensez que le virus de daCode risque de
vous attraper, il vous faudra bien un jour ou l'autre passer
par le CVS.
* le tgz :
	$ wget http://perso.linuxfr.org/penso/daCode.tar.gz
* le CVS :
	$ cvs -d:pserver:anonymous@cvs.dacode.sourceforge.net:/cvsroot/dacode login
	CVS password :  [tapez ENTREE]
	$ cvs -z3 -d:pserver:anonymous@cvs.dacode.sourceforge.net:/cvsroot/dacode co daCode
Puis vous pouvez laisser reposer le modem.

Par rapport au tgz, le CVS parait rebutant au premier abord mais il ne faut
pas s'y fier:
	a) ca vous évite d'avoir à taper le `tar zxvf daCode.tar.gz'
	b) Ne vous souciez plus du password, ni des URLS, ni des
	   logins. Plus rien de tout cela ne sera demandé ensuite.
Il aura suffi de faire du copier/coller pour cette première récupération.

Quelle que soit la methode, on se retrouve avec cette arborescence (elle
peut être légèrement différente, suivant les développements de daCode) :

	$ tree -d daCode | grep -v CVS
daCode
|-- doc
|   |-- html
|   |-- script
|   |-- sgml
|   |-- txt
|   `-- xml
`-- src
    |-- htdocs
    |   |-- admin
    |   |-- board
    |   |-- comments
    |   |-- images
    |   |   `-- section
    |   |-- messages
    |   |-- news
    |   |-- pda
    |   |-- poll
    |   |-- themes
    |   |   |-- daweb
    |   |   |	`-- images
    |   |   |-- kde2
    |   |   |	`-- images
    |   |   |-- linuxfr
    |   |   |	`-- images
    |   |   |-- phpnukeopenmind
    |   |   |	`-- images
    |   |   |	    `-- section
    |   |   |-- slashdot
    |   |   |   `-- images
    |   |   |       `-- section
    |   |   `-- wm
    |   |       `-- images
    |   |-- users
    |   |-- w
    |   |-- wap
    |   `-- webcam
    `-- phplib
        `-- themes
            |-- daweb
            |-- kde2
            |-- linuxfr
            |-- lynx
            |-- phpnukeopenmind
            |-- printable
            |-- slashdot
            `-- wm

C'est maintenant que les choses sérieuses vont commencer.
Comme on a décidé de publier sur le web, on va avoir
besoin d'un petit coup de pouce de Root. Autant Le
prévenir tout de suite. Après Lui avoir offert une Guinness,
demandez-lui gentiment:
* une base de données pour stocker vos infos.

Pour la base de données, l'Administrateur n'a pas besoin de se
connecter en root car MySQL sait identifier root avec son mot
de passe MySQL.

	[operator]$ mysql_setpermission -u root
Password for user root to connect to MySQL:                  ******
######################################################################
## Welcome to the permission setter 1.2 for MySQL.
## made by Luuk de Boer
######################################################################
What would you like to do:
  1. Set password for a user.
  2. Add a database + user privilege for that database.
     - user can do all except all admin functions
  3. Add user privilege for an existing database.
     - user can do all except all admin functions
  4. Add user privilege for an existing database.
     - user can do all except all admin functions + no create/drop
  5. Add user privilege for an existing database.
     - user can do only selects (no update/delete/insert etc.)
  0. exit this program

Make your choice [1,2,3,4,5,0]:                                2

Which database would you like to add:                          dabase    
The new database dabase will be created

What username is to be created:                                daiouser
Username = daiouser
Would you like to set a password for  [y/n]:                   y
What password do you want to specify for :                     dapass
Type the password again:                                       dapass
We now need to know from what host(s) the user will connect.
Keep in mind that % means 'from any host' ...
The host please:                                               localhost
Would you like to add another host [yes/no]:                   no
Okay we keep it with this ...
The following host(s) will be used: localhost.
######################################################################

That was it ... here is an overview of what you gave to me:
The database name	: dabase
The username 		: daiouser
The host(s)		: localhost
######################################################################

Are you pretty sure you would like to implement this [yes/no]: yes
Okay ... let's go then ...



Root doit vous communiquer ces indications:
le nom de la base, le nom du user, le mot de passe.
Maintenant le travail de Root est terminé, on revient à notre
login Unix `dacode' auquel Il a transmis les indications.

En fait, on va s'empresser de les oublier, mais auparavant
on va les inscrire dans un fichier de configuration de daCode
que vous devez impérativement créer:
	$ cat daCode/config.site 
<?
	$this->sql_host = "localhost";
	$this->sql_user = "daiouser";
	$this->sql_passwd = "dapass";
	$this->sql_db = "dabase";
	$this->basehref = "http://exosmose.localdomain/~dacode/daroot";
	$this->name = "Test daCode";
	$this->titledefault = "Un forum, des fora";
?>

Tant que vous y êtes, remplacez exosmose.localdomain par votre
propre machine.
	$ uname -n
	exosmose.localdomain
Mais laissez tomber `basehref'. On verra cela plus loin.


Avant d'oublier votre mot de passe, ca serait bien
de mettre le nez dans le cambouis pour voir si ca marche.

	$ mysql dabase -udaiouser -pdapass

mysql> create table matable (madate date);
Query OK, 0 rows affected (0.00 sec)

mysql> insert into matable values (now());
Query OK, 1 row affected (0.00 sec)

mysql> show tables;
+------------------+
| Tables in dabase |
+------------------+
| matable          |
+------------------+
1 row in set (0.00 sec)

mysql> describe matable;
+--------+------+------+-----+---------+-------+
| Field  | Type | Null | Key | Default | Extra |
+--------+------+------+-----+---------+-------+
| madate | date | YES  |     | NULL    |       |
+--------+------+------+-----+---------+-------+
1 row in set (0.00 sec)

mysql> select * from matable;
+------------+
| madate     |
+------------+
| 2001-01-04 |
+------------+
1 row in set (0.00 sec)

	### Ca a l'air de marcher, on fait le menage:

mysql> drop table matable;
Query OK, 0 rows affected (0.00 sec)

mysql> show tables;
Empty set (0.00 sec)

mysql> exit
Bye


Vous vous souvenez toujours du mot de passe ? Chouette!

Modifiez daCode/sql/dacode.mysql à la ligne :

INSERT INTO users (id,login,passwd,level,email) VALUES ('2', 'admin','X','6291456','root');

et remplacez root par votre adresse email.

Créez vos tables grace au script SQL qu'on trouve bizarrement dans doc/ :
	$ mysql dabase -vvv -udaiouser -pdapass < daCode/sql/dacode.mysql 

Il est possible que daCode fournisse plus tard un autre fichier
`dump.sql' qui contiendrait des exemples, pour accélerer les tests.
L'installation de ce script sera similaire.


Vous vous souvenez de config.site ? On trouvait cela dedans :

	$this->basehref = "http://exosmose.localdomain/~dacode/daroot";

Cela indique la racine de l'arborescence de l'application daCode.
Afin de faciliter l'installation, nous allons utiliser un lien
symbolique:
	$ cd /home/dacode/public_html
	$ ln -s /home/dacode/daCode/src/htdocs daroot

Dans la mesure où vous avez les droits unix, vous pouvez changer
votre vision Apache a volonté. Vous choisissez `basehref' comme
vous voulez, puis vous placez `daroot' la ou Apache va aller le
chercher. Nous allons étudier quelques cas, mais avant cela
déplaçons notre lien afin que la suite soit plus lisible:
	$ mv daroot /tmp/

Monsieur Bidule souhaite récuperer daCode chez lui ?
$this->basehref = "http://exosmose.localdomain/~bidule/daroot";
	$ cp -va /tmp/daroot ~bidule/public_html/

Monsieur Bidule veut changer l'appellation ?
$this->basehref = "http://exosmose.localdomain/~bidule/phpnuke";
	$ cd ~bidule/public_html/ && mv daroot phpnuke

Monsieur Bidule veut faire une place centrale a daCode ?
$this->basehref = "http://exosmose.localdomain/~bidule";
	$ cd ~bidule
	$ mv public_html public_html.old 
	$ cp -va /tmp/daroot ./
	$ mv daroot public_html


Maintenant que basehref est positionnée comme vous le souhaitez,
il reste à générer un fichier de configuration qui prenne vos données
en compte. Pour cela, vous pouvez copier daCode/src/phplib/config.sample
dans daCode/src/phplib/config.php3 et remplacer dans ce fichier les
variables définies dans daCode/config.site. Une autre solution consiste
à se placer dans le répertoire daCode et taper
        $ make reconf
qui automatise cette étape.

Vous pouvez maintenant consulter daCode:
	$ netscape [le basehref que vous avez défini dans config.site]

C'est l'instant crucial. Ca peut marcher nickel, ou bien sur
trois pattes ou bien pas du tout.

Ne paniquons pas. Qu'avons nous sous la main pour comprendre ce
qui se passe ?

* la liste de diffusion dacode-dev@linuxfr.org

* confrontez vos résultats aux serveurs daCode qui tournent:
	- http://linuxfr.org (n'est pas une machine de test)
	- http://www.dacode.org
	- http://demo.dacode.org

* le script php <? phpinfo(); ?> qui affiche la config
  sur laquelle repose daCode. Si vous avez une config
  exotique (= qu'on n'a jamais vue) il faudrait arriver
  à nous la décrire.

* Apache peut planter pour des raisons d'extensions, pour
  des problemes de droits d'accès unix, parce qu'il interdit
  les liens symboliques. Généralement le message d'erreur
  est explicite.

* les commandes SQL peuvent être loggées dans un fichier (variable
  $this->sql_logfile dans config.php3)

* ca peut etre utile d'avoir sous les yeux l'arborescence
  de daCode. Vous pourrez suivre les URLs :
	$ cd /tmp/daroot/
	$ tree -P "*php3" | grep -v CVS
.
|-- admin
|   |-- index.php3
|   |-- mod.php3
|   |-- modpoll.php3
|   |-- modusers.php3
|   |-- tip_section_add.php3
|   |-- topics_add.php3
|   |-- topics_edit.php3
|   `-- viewfile.php3
|-- board
|   |-- add.php3
|   |-- index.php3
|   `-- info.php3
|-- comments
|   |-- add.php3
|   |-- index.php3
|   |-- score.php3
|   |-- thread.php3
|   `-- view.php3
|-- dacode.php3
|-- gen.php3
|-- images
|   `-- section
|-- index.php3
|-- messages
|   |-- add.php3
|   |-- post.php3
|   `-- view.php3
|-- news
|   |-- send_email.php3
|   |-- send_email_view.php3
|   `-- view_modero.php3
|-- pda
|   |-- index.php3
|   `-- news.php3
|-- poll
|   |-- index.php3
|   `-- new.php3
|-- redirect.php3
|-- search.php3
|-- short-rss.php3
|-- short.php3
|-- submit.php3
|-- themes
|   |-- daweb
|   |	`-- images
|   |-- kde2
|   |   `-- images
|   |-- linuxfr
|   |   `-- images
|   |-- phpnukeopenmind
|   |	`-- images
|   |	    `-- section
|   |-- slashdot
|   |   `-- images
|   |       `-- section
|   `-- wm
|       `-- images
|-- users
|   |-- index.php3
|   |-- login.php3
|   |-- modpasswd.php3
|   |-- myposts.php3
|   |-- password.php3
|   `-- settings.php3
|-- view_attach.php3
|-- w
|   `-- news.php3
|-- wap
|   |-- index.php3
|   `-- news.php3
`-- webcam
    |-- image.php3
    |-- submit.php3
    |-- webcam_admin.php3
    `-- webcam_change.php3

* les scripts peuvent planter pour de nombreuses raisons de plantages. ;)

  Les méchants bugs bloquants ne trainent pas trop dans daCode
  parce qu'on n'a qu'une version de développement et qu'il faut
  impérativement qu'on puisse travailler dessus. Si un patch
  provoque un bug bloquant, on va vite s'en apercevoir, on
  découvrira vite d'ou ça vient, et on décidera vite de ce
  qu'on fait : le corriger si c'est facile, ou bien abandonner
  le patch qui l'a introduit. Il faut de la stabilité parce qu'il
  y a des sites comme LinuxFR qui s'appuient sur daCode. Le vôtre
  aussi, peut-être.

  Les petits bugs gentils, les warnings, les boites pas alignées,
  le code source html bancal, les icones moches, les docs sans accents
  avec pleins de fôtes, etc. sont légions. On les a mis là exprès pour
  vous embêter. Le but inavouable est de vous torturer psychologiquement
  jusqu'à ce que vous soumettiez un patch.


* si on découvre un bug, on le corrige dans le CVS. ce qui
  permet a tout le monde de mettre à jour sa config facilement:
  	[allumer le modem]
  	$ cvs update -d -P
	[éteindre le modem]
	recommencer les tests...


-*-

Chapitre 2 :
Après ça, on va voir comment faire quelques tests pour s'assurer que les
modules essentiels sont fonctionnels.


-*-

Chapitre 3 : observer le fonctionnement du serveur

A. Le cache

Le cache de dacode permet de stocker des fragments HTML
dans le but d'éviter de faire des appels dynamiques PHP
et MySQL. Ces appels sont coûteux et doivent être évités
dans la mesure du possible.

Deux types de fragments sont cachés: les boites et les
pages. Une page est un document Html complet, alors qu'une
boite est un bout de Html qui est inséré dans un document
généré par daCode. Nous allons séparer ces deux aspects:

	$ mkdir dacache
	$ mkdir dacache/boxes dacache/pages

Le cache est géré par Apache. Il faut que celui ci puisse
écrire et lire dans le cache. Pour l'instant, on donne
des droits suffisants. On affinera plus tard...

	$ chmod o+rwx dacache/boxes/ dacache/pages/

Il nous faut rajouter dans le `config.site' nos emplacements:
	$ grep cache daCode/config.site
	    $this->cachedir = "/home/dacode/dacache/boxes/";
	    $this->htmldir  = "/home/dacode/dacache/pages/";
	$ cd daCode; make reconf
va recréer le fichier daCode/src/phplib/config.php3

Maintenant, le cache est opérationnel. Si vous
faites appel à votre site daCode, les répertoires vont
se remplir de fichiers petit à petit. Il n'y a pas
d'intervention particulière de maintenance à prévoir.

Les noms de fichiers ressemblent à ceci:
	$ ls dacache/*
	dacache/boxes:
	backends_agenda--.,0.html  dacode_dacode--,0.html.1.0.
	backends_kernel--.,0.html  sidebox_topics--,0.html.1.0.

	dacache/pages:
	index,0,1,0.html

L'entête (backend_agenda) décrit quel est le script qui est à
l'origine de la création de ce fichier de cache. Les suffixes
sous forme de chiffres , séparés par des points ou des virgules
représentent un Profil d'utilisateur.
- Un utilisateur anonyme
- Un utilisateur ayant choisi le theme Slashdot
- Un utilisateur ayant choisi le theme Defaut et [un autre truc]. (TODO)

Deux remarques:
- Plus les profils auront d'options, plus le cache devra créer de fichiers.
- Vous pouvez peut être trouver commode de vous représenter les profils
  comme étant une partie de la base de données de daCode stockée dans les
  cookies sur les navigateurs et auquel daCode accède grace à la classe
  PHP `Session'. Cette représentation est en grande partie erronée, mais
  je la trouve utile pour comprendre le fonctionnement du serveur avec un
  niveau d'abstraction élevé.

B. Les processus

C. Les logs
	$ cat /tmp/dacode-sqllog

D. La base MysQL
	descriptions des tables


-*-

Chapitre 4 : mise en production

On va créer un petit comité de pilotage pour cette mise en
production. Qui trouvons nous ?

- apache (httpd)
C'est le daemon qui est chargé de délivrer les pages. il collabore
avec PHP et MySQL pour accomplir son job.

- dacode
Il se charge du debugging et de la mise a jour du code, de
l'installation des nouvelles versions. Sa tache n'est pas facile
et il a intérêt à disposer d'une machine a part pour tester
les versions de développement, à bien comprendre son code,
et à maitriser CVS.

- dagraf
C'est le graphiste de l'équipe. il s'occupe du design, des themes,
il crée aussi les topics. Il devrait collaborer étroitement avec
`dacode' et il serait utile de leur créer un groupe en commun.

- Root
Il s'occupe de la bonne marche du site. il affecte les droits de
chacun des utilisateurs de maniere a ce que personne ne marche sur
les pieds des autres. il est chargé de la sécurité et il devraient
donc controler les scripts et vérifier que le fonctionnement
quotidien du site ne nuit pas aux ressources du serveur.
(controle du cache, des process, de l'occupation RAM, backups, logs).

Root blinde les droits.
/* TODO
 * a relire,
 * a tester,
 * faire un script
 */

	# grep dacode /etc/group 
dacode:x:508:dacode,dagraf
	# tree -gifpu ~dacode

[drwx------ dacode     root  ]  /home/dacode/daCode

[drwx------   root     root  ]  /home/dacode/dacache
[drwx------ apache     root  ]  /home/dacode/dacache/boxes
[drwx------ apache     root  ]  /home/dacode/dacache/pages

[-r-------- apache     root  ]  /home/dacode/daCode/src/phplib/config.site
[lrwxrwxrwx   root     root  ]  /home/dacode/daroot -> /home/dacode/daCode/src/htdocs

[drwx------ dacode     root  ]  *CVS*

[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/phplib

[drwxr-xr-x dacode   dacode  ]  /home/dacode/daCode/doc
[drwxr-xr-x dacode   dacode  ]  /home/dacode/daCode/doc/html
[drwxr-xr-x dacode   dacode  ]  /home/dacode/daCode/doc/script
[drwxr-xr-x dacode   dacode  ]  /home/dacode/daCode/doc/sgml

[drwxr-xr-x dagraf   dacode  ]  /home/dacode/daCode/src/htdocs/images
[drwxr-xr-x dagraf   dacode  ]  /home/dacode/daCode/src/htdocs/images/section
[drwxr-xr-x dagraf   dacode  ]  /home/dacode/daCode/src/htdocs/images/themes
[drwxr-xr-x dagraf   dacode  ]  /home/dacode/daCode/src/htdocs/images/themes/slashdot
[-rw-r--r-- dagraf   dacode  ]  /home/dacode/daCode/src/htdocs/slashdot.css
[-rw-r--r-- dagraf   dacode  ]  /home/dacode/daCode/src/htdocs/style.css
[drwxr-xr-x dagraf   dacode  ]  /home/dacode/daCode/src/phplib/themes
[drwxr-xr-x dagraf   dacode  ]  /home/dacode/daCode/src/phplib/themes/default
[drwxr-xr-x dagraf   dacode  ]  /home/dacode/daCode/src/phplib/themes/slashdot

[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/admin
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/board
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/comments
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/messages
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/news
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/poll
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/users
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/w
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/wap
[drwxr-xr-x dacode     root  ]  /home/dacode/daCode/src/htdocs/webcam


-*-

Chapitre 5 : Code Fréquemment Réutilisé
On regarde ensuite un peu plus en detail: la doc, la difference entre
htdocs et phplib, les themes, l'i18n, les sessions et les cookies.