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

Ce document propose de mettre en oeuvre daCode en
explorant en dtail chaque tape.


Chapitre 1 : installer daCode sur localhost


daCode est une application Web base sur un langage de scripts (PHP)
et une base de donnes (MySQL ou PostgreSQL, peut-6tre d'autres
ultrieurement).

Les applications Web sont un peu particulires  installer.
Il faut rcuprer un package, mettre en place des scripts
et faire une initialisation de la base de donnes. C'est
une logique assez diffrente d'un logiciel `normal', mais
en utilisant le bon outil, c'est trs 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
manire transparente et aussi de participer au dveloppement.

daCode bouge beaucoup. Ce doit tre assez gnral pour les
applications Web. Vous avez intrt de prvoir des
mises  jour frquentes. Se lancer dans CVS est un bon
investissement.

Avant de commencer  installer daCode, on va prparer un petit nid
douillet pour daCode et vrifier que tout est en place.
On peut crer un utilisateur spcifique `dacode' si
on veut bien sparer 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 dveloppement.


Maintenant, on va vrifier que votre config est bonne.

Chez moi, je procde 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
problme de droits d'accs et corrigez-le avec `chmod o+rx'.
Apache va avoir besoin de lire vos fichiers et de parcourir
vos rpertoires:
	$ 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 ppin avec
apache ou PHP. Ouille :(
Si ca marche, regardez dans les infos la version de PHP
et la prsence des Extensions MySQL et Apache. On pourra en avoir
besoin plus tard s'il y a des problmes.
	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 rcuperer daCode.
Choisissez votre stratgie. Si c'est juste pour voir la tte
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 premire rcupration.

Quelle que soit la methode, on se retrouve avec cette arborescence (elle
peut tre lgrement diffrente, suivant les dveloppements 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 srieuses vont commencer.
Comme on a dcid de publier sur le web, on va avoir
besoin d'un petit coup de pouce de Root. Autant Le
prvenir tout de suite. Aprs Lui avoir offert une Guinness,
demandez-lui gentiment:
* une base de donnes pour stocker vos infos.

Pour la base de donnes, 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 imprativement crer:
	$ 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.

Crez 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 acclerer 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
dplaons notre lien afin que la suite soit plus lisible:
	$ mv daroot /tmp/

Monsieur Bidule souhaite rcuperer 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 positionne comme vous le souhaitez,
il reste  gnrer un fichier de configuration qui prenne vos donnes
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 dfinies dans daCode/config.site. Une autre solution consiste
 se placer dans le rpertoire daCode et taper
        $ make reconf
qui automatise cette tape.

Vous pouvez maintenant consulter daCode:
	$ netscape [le basehref que vous avez dfini 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 rsultats 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 dcrire.

* Apache peut planter pour des raisons d'extensions, pour
  des problemes de droits d'accs unix, parce qu'il interdit
  les liens symboliques. Gnralement le message d'erreur
  est explicite.

* les commandes SQL peuvent tre logges 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 mchants bugs bloquants ne trainent pas trop dans daCode
  parce qu'on n'a qu'une version de dveloppement et qu'il faut
  imprativement qu'on puisse travailler dessus. Si un patch
  provoque un bug bloquant, on va vite s'en apercevoir, on
  dcouvrira vite d'ou a vient, et on dcidera 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 vtre
  aussi, peut-tre.

  Les petits bugs gentils, les warnings, les boites pas alignes,
  le code source html bancal, les icones moches, les docs sans accents
  avec pleins de ftes, etc. sont lgions. On les a mis l exprs pour
  vous embter. Le but inavouable est de vous torturer psychologiquement
  jusqu' ce que vous soumettiez un patch.


* si on dcouvre 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 :
Aprs 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 coteux et doivent tre vits
dans la mesure du possible.

Deux types de fragments sont cachs: les boites et les
pages. Une page est un document Html complet, alors qu'une
boite est un bout de Html qui est insr dans un document
gnr par daCode. Nous allons sparer ces deux aspects:

	$ mkdir dacache
	$ mkdir dacache/boxes dacache/pages

Le cache est gr 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 recrer le fichier daCode/src/phplib/config.php3

Maintenant, le cache est oprationnel. Si vous
faites appel  votre site daCode, les rpertoires vont
se remplir de fichiers petit  petit. Il n'y a pas
d'intervention particulire de maintenance  prvoir.

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'entte (backend_agenda) dcrit quel est le script qui est 
l'origine de la cration de ce fichier de cache. Les suffixes
sous forme de chiffres , spars par des points ou des virgules
reprsentent 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 crer de fichiers.
- Vous pouvez peut tre trouver commode de vous reprsenter les profils
  comme tant une partie de la base de donnes de daCode stocke dans les
  cookies sur les navigateurs et auquel daCode accde grace  la classe
  PHP `Session'. Cette reprsentation est en grande partie errone, 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 crer un petit comit de pilotage pour cette mise en
production. Qui trouvons nous ?

- apache (httpd)
C'est le daemon qui est charg de dlivrer 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 intrt  disposer d'une machine a part pour tester
les versions de dveloppement,  bien comprendre son code,
et  maitriser CVS.

- dagraf
C'est le graphiste de l'quipe. il s'occupe du design, des themes,
il cre aussi les topics. Il devrait collaborer troitement avec
`dacode' et il serait utile de leur crer 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 scurit et il devraient
donc controler les scripts et vrifier 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 Frquemment Rutilis
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.

