Installer GeneWeb en mode CGI sur un serveur

Language:	English • français

Quand le mode daemon n'est pas utilisable, GeneWeb peut être activé en mode CGI. Ceci est fréquemment la situation des serveurs hébergés.

En mode CGI, GeneWeb fonctionne derrière un serveur HTTP tel que Apache, et est activé par ce serveur via une commande CGI. La première étape de l'installation en mode CGI consiste dont à vérifier ce mode de fonctionnement de votre serveur HTTP.

La deuxième étape consiste à installer GeneWeb proprement dit dans une organisation de dossiers adaptée à votre environnement (processeur, 32/64 bits, OS).

Vérification des services Web et CGI

La vérification du service Web est obtenue en affichant dans votre navigateur favori le contenu du fichier index.html.

(server):~#ls -al index.html
-rwxr-xr-x  1 username usergroup    290 Nov 22 22:29 index.html
(server):~#cat index.html
<!DOCTYPE html">
<html xmlns="http://www.w3.org/1999/xhtml">
<body>
This is a minimal index.html page
</body>
</html>
(server):~#

Typing the following in your browser window:

http://my_server_address/index.html

should display

This is a minimal index.html page

Le service CGI est vérifié en déclenchant l'exécution du fichier test-cgi.sh :

(server):~#cd cgi-bin
(server):~/cgi-bin#ls -al test-cgi.sh
-rwxr-xr-x  1 username usergroup    290 Nov 22 22:29 test-cgi.sh
(server):~/cgi-bin#cat test-cgi.sh
#!/bin/sh
echo 'Content-type: text/html'
echo  
echo '<!DOCTYPE html">'
echo '<html xmlns="http://www.w3.org/1999/xhtml">'
echo '<body>'
echo 'This is a test for cgi commands'
echo '</body>'
echo '</html>'
(server):~/cgi-bin#

En saisissant la commande suivante dans votre navigateur :

 http://my_server_address/cgi-bin/test-cgi.sh

vous devriez obtenir la réponse suivante :

This is a test for cgi commands

Notez les droits de propriétaire et d'accès en lecture/écriture/exécution de ce fichier. Voir la section #Droits d'accès et protection.

La localisation de ces fichiers peut varier selon le service d'hébergement que vous utilisez, et est décrite en détail dans la section #Examples d'organisation des dossiers.

Le dossier cgi-bin

Le dossier cgi-bin contient les commandes CGI qui seront exécutées pas le serveur lors des requêtes envoyées par un navigateur client.

- cgi-bin: Le dossier contenant lesexécutables CGI.
  - gwd.sh
  - test-cgi.sh

Le contenu de gwd.sh est :

(server):~/cgi-bin > cat gwd.sh
#!/bin/sh
BIN_DIR=/root/geneweb-distribution/gw
BASE_DIR=/root/geneweb-bases
OPTIONS="-robot_xcl 19,60 -allowed_tags ./tags.txt -hd ./"
$BIN_DIR/gwd -cgi  $OPTIONS   -bd $BASE_DIR   > ./gwd.log 2>&1

Le fichier gwd-7.00.sh est un script shell qui lance gwd avec les paramètres appropriés :

Il contient les definitions suivantes :

DIR pointe vers le dossier gw contenant les divers exécutables voir GeneWeb (voir distibution).
BASE_DIR pointe vers le dossier contenant vos bases généalogiques (see bases).

Le détail de ces deux cheminoms peut varier en fonction de l'organisation de dossiers que vous avez retenue (voir #Examples d'organisation des dossiers).

OPTIONS définit les paramètres de lancement de gwd, voir gwd pour les détails.

Il est possible de conserver dans ce dossier plusieurs fichiers gwd-xx.sh pointant vers différents dossiers contenant différentes versions de GeneWeb, ou démarrant avec des paramètres OPTIONS différents.

Comme il est discuté en ???, les paramètres de lancement de gwd peuvent être rassemblés dans un fichier gwd.arg situé dans le dossier gw. Notez que dans ce fichier, le nom du paramètre et sa valeur sont sur deux lignes séparées. Faites aussi attention au choix de la fin de ligne (CR, LF, CR/LF) qui est différent selon l'environnement Linux, macOS et Window.

(server):~ > cat /home/geneweb-distribution/gw/gwd.arg
-cgi
-bd
~/bases
-hd
./
-robot_xcl 
19,60
-allowed_tags
./tags.txt
(server):~ >

Les dossiers distribution et bases

La suite de l'organisation des dossiers suit la même structure que dans le cas d'installation classique avec un ou plusieurs dossiers distribution GeneWeb, et le dossier GeneWeb-Bases contenant une ou plusieurs bases généalogiques.

Examples d'organisation des dossiers

Les organisations suivantes ont été testées sur plusieurs services d'hébergement :

OVH-Webm

www
- cig-bin
  - gwd.sh
  - test-cgi.sh
- geneweb-distrib
- geneweb-bases
- gw -> geneweb-distrib/gw
- index.html

OVH-VPS

/
- root
  - geneweb-distrib
  - geneweb-bases
- usr
  - lib
    - cig-bin
      - gwd.sh
      - test-cgi.sh
- var
  - www
    - gw -> geneweb-distrib/gw
    - index.html

1&1

home
- cig-bin
  - gwd.sh
  - test-cgi.sh
- geneweb-distrib
- geneweb-bases
- gw -> geneweb-distrib/gw
- index.html

Lien vers les fichiers style

Dans le cas d'un serveur hébergé en mode CGI, les fichiers style (.css) et javascript (.js) sont renvoyés vers votre navigateur par le serveur HTTP plutôt que par gwd. Il est donc nécessaire de fournir au premier un lien situé à la racine web vers les fichiers appropriés de la distribution.

L'exemple ci-dessous correspond à l'organisation d'un serveur OVH-VPS.

root@vps265730:/var/www# ls -al
total 660
drwxr-xr-x  7 root root   4096 Sep 25 18:40 .
drwxr-xr-x 12 root root   4096 Apr 16  2016 ..
drwxr-xr-x  4 root root   4096 Nov 23 15:41 gw -> /root/GW/GeneWeb-7.00/gw
-rw-r--r--  1 root root   3514 Jun 23 13:19 index.html
drwxr-xr-x  2 root root   4096 Apr 16  2016 private
drwxr-xr-x  2 root root   4096 Apr 16  2016 public
-rw-r--r--  1 root root     27 Apr 28  2016 robot.txt
root@vps265730:/var/www#

Vous devez signaler à gwd l'existence de ce lien en ajoutant dans le fichier de configuration .gwf le paramètre

 static_path=../gw/etc

Notez les .. en tête du lien dus au fait que l'exécution du script démarrant gwd se fait dans le dossier cgi_bin, un niveau en dessous de la racine web de votre serveur.

http://server_address/cgi-bin/gwd-7.00.sh

1&1 hosting, GeneWeb 5 and 6 (archive)

(Conservé ici pour archive)

The following applies to 1&1 hosting, and may differ on other hostings. On this web site, we can easily switch between two versions of GeneWeb: 5.00 and 6.00.

Directories and files

Files and directories on 1&1.

- mybases: The bases directory, beside the CGI-root directory.
  - mybases.gwb
  - cnt
  - images
- root: The CGI-root directory.
  - basesxg: An alternative bases directory.
  - css: A copy of the gw/css directory. This directory is used by the Apache server.
  - gw: The gw directory of the GeneWeb distribution.
  - gwenv: The gw directory of the Geneweb-5 distribution.
  - igw: The images directory for Geneweb-5.
  - images: A directory with copies of gw/images/gwback.jpg and gw/images/gwlogo_bas.png
  - pub: A directory where are readable copies of the CGI scripts (this website is a demo site).
  - gw6.cgi: The CGI script which launches GenWeb-6.
  - gw5.cgi: The CGI script which launches GenWeb-5.
  - issue6.cgi: A test script which displays information about the environment of the server and checks size and md5sum for the gwd binary file.
  - issue5.cgi: The same script, but for the GeneWeb-5 version

You need the “exec” permission on the files gw/gwd, gw/gwsetup, and files used by gwsetup (gw/gwc*, gw/gwu,gw/consang, gw/update_nldb). The gwd.arg file is empty.

The databases folder bases must be protected either by a .htaccess file, either by a location out of the HTTP server scope. It does not need to be accessible by the HTTP server.

Description of the CGI script

Main parameters:

PWD=$(pwd)
LNG="fr"
GENEWEBSHARE=$PWD/gw
GENEWEBDOC=$PWD/gw/doc
GENEWEBDB=$PWD/../bases
DAEMON=$GENEWEBSHARE/gwd
LOGFILE=$GENEWEBDB/gw.log

The CGI working directory.
The language for the user interface.
The programs folder.
The documentation folder (obsolete).
The databases folder. 
The program gwd itself.
Gwd log file, it helps to solve problems.

Note that although called DAEMON, gwd does not run in -daemon mode but in -cgi mode.

Be carefull when using a log file, its size can increase quickly, don’t forget to delete it from time to time.

OPTIONS="-blang -robot_xcl 40,70 -max_clients 15 -conn_tmout 120 -min_disp_req 30 -images_url http://myserver.net/gw/images"
# -allowed_tags $GENEWEBDB/tags.txt
cd $GENEWEBSHARE
$DAEMON -hd$GENEWEBSHARE -dd$GENEWEBDOC -bd$GENEWEBDB -lang$LNG -log$LOGFILE -cgi $OPTIONS  2>/dev/null

Misc. options:

robot_xcl: To protect your data from HTTrack or WebSite Extractor.
conn_tmout: For statistics on the bottom line.
images_url: Icons and images are not sent by GeneWeb, but by your HTTP server (not CGI).
allowed_tags: Usefull option if you use HTML tags not in default_good_tag_list.

Windows

Under Windows calling a CGI script using batch and cmd.exe can be tricky. An alternative is to directly call a copy of gwd.exe with its arguments file gwd.arg in Apache /cgi-bin/ directory file.

Gwd will work behind Apache calling http://localhost/cgi-bin/gwd.exe.

cgi-bin
- gwd.exe
- gwd.arg

Edit gwd.arg to point your local GeneWeb installation, for example if it is C:\Program Files (x86)\geneweb\:

-hd
C:\Program Files (x86)\geneweb\gw
-bd
C:\Program Files (x86)\geneweb\bases
-log
C:\Program Files (x86)\geneweb\geneweb.log
-images_dir
C:\Program Files (x86)\geneweb\gw\images
-cgi

Problems to solve: - Portrait (all images with m=IMH) are not shown or are corrupted (#103). - Minor problems in 7.00 with loading of new .css/.js files, specialy for templm (#356).

Images missing

-images_dir parameter create links to local image files like file:///c:\path\to\myimage.jpg that are not shown for security reason under some browser (like Chrome for ex.). An alternative to previous configuration is to switch to -images_url parameter so that gwd uses relatives paths for images and to create a virtual directory in your httpd server.

In gwd.arg, modify:

-images_url
/images

If you use Apache, edit httpd.conf to have those lines, then restart httpd.exe:

LoadModule access_compat_module modules/mod_access_compat.so
LoadModule alias_module modules/mod_alias.so

Alias /images " C:\Program Files (x86)\geneweb\gw\images"

<Directory " C:\Program Files (x86)\geneweb\gw\images">
  Options None
  AllowOverride All
  Order allow,deny
  Allow from all
</Directory>

Script pour installer sur votre serveur une copie de votre base

Les fichiers qui suivent s'adressent aux usagers expérimentés et familiers avec les scripts shell et les subtilités de Linux. A utiliser avec précautions. Merci de signaler en retour les erreurs ou amélioration.

Le script base-upload.sh (download it) prend base_name comme argument, et en option images or src. Il télécharge vers le serveur une copie de votre base présente sur votre ordinateur personnel (Linux ou Mac seulement) en effectuant les étapes suivantes :

créer une copie fraîche du fichier base.gw à partir de votre base sur votre ordinateur eprsonnel.
produit un listing des dossiers bases/images/base bases/src/base et bases/src/base/images dans trois fichiers ls-xxx.txt.
construit un fichier remote.sh (voir remote-base.sh ou remote-files.sh) selon le second paramètre.
construit un fichier tar contenant base.gw, history, remote.sh et els trois fichiers ls-*.txt ci-dessus.
envoie ce fichier tar au serveur distant.
déclenche sur le serveur distant le dépliement du fichier tar et l'exécution du fichier script remote.sh.

Selon la disponibilité de /usr/bin/mail sur votre serveur, le résultat de ce script pourra être un mail contenant un rapport d'erreur et les différences entre les dossiers images.

Cette procédure sauvegarde la version antérieure de votre base avec un tag "yyyy-mm-dd-hh:mm:ss". Avec le temps, il peut être souhaitable de nettoyer ces fichiers archives.

Le lancement du script avec le paramètre images ou src installe sur votre serveur distant une copie des dossiers correspondants de votre ordinateur personnel. Selon la taille de ces dossiers et le nombre de nouvelles images à télécharger, il est possible qu'un téléchargement image par image soit préférable.

Mise au point d'un serveur distant

Mettre au point un serveur distant implique de nombreux aspects qui peuvent en compliquer la bonne fin. Une approche systématique et quelques outils peuvent aider cette tâche.

Vérifiez que votre serveur HTTP fonctionne correctement en visualisant le contenu du fichier index.html situé à la racine web de votre serveur.
Vérifiez le bon fonctionnement du mécanisme CGI en interrogeant http://your_server_name/cgi-bin/test-cgi.sh à partir de votre navigateur (voir #Vérification des services Web et CGI).

Si votre serveur renvoie le message "Internal server error", plusieurs hypothèses sont possibles :

Votre script CGI ne fonctionne pas correctement. Lancez son exécution directement à partir d'une fenêtre terminal vers vorte serveur (./test-cgi.sh).
Votre serveur HTTP peut n'accepter que des fichiers avec l’extension .cgi. Renommez test-cgi.sh en test-cgi.cgi et essayez à nouveau.
Les deux premières lignes de votre script ne respectent pas le format imposé (la seconde ligne doit être vide). Notez que la formule "Content-type text/html\n\n" n'a pas fonctionné dans mes essais).
Vérifiez aussi que vos "fin de ligne" (EOL) respectent la convention de votre serveur qui peut être différente de celle de votre ordinateur personnel!
examinez le log d'erreurs de votre serveur HTTP en tapant :

tail ~/logs/access.logs.current

(la localisation de ce fichier peut être différente dans vorte environnement. Vous pouvez la découvrir en tapant find / -name access -print).

L'examen de ce fichier log peut vous donner une indication de la nature de votre problème.

Un autre problème classique est celui des droits de propriété et d'accès aux fichiers (voir ci-dessous).
Regardez aussi le fichier log de gwd précisé dans la commande de lancement.
Il est possible que GeneWeb ne fonctionne que partiellement, manquant par exemple certains fichiers style ou JavaScript. Une manière de vérifier et de tester cette situation consiste à examiner le fichier source de votre page HTML (les navigateurs fournissent des outils "développeurs" pour cela), et de cliquer sur le lien vers les fichiers qui semblent manquer. Le message d'erreur en retour vous renseignera : "File not found", "You do not have access permission", ...

Souvenez vous que certains fichiers vous sont renvoyés par le serveur HTTP plutôt que par gwd.

Droits d'accès et protections

En mode CGI, gwd fonctionne derrière un serveur HTTP, typiquement Apache. De ce fait, le processus gwd s'exécute sous l'identification du serveur HTTP. Avec Apache, cette identité est définie dans le fichier http.conf, et sa valeur apr défaut est user: _www and group: —www. Selon votre envoironnement, vous pourrez avoir ou ne pas avoir accès à ces éléments de configuration. Vous devez donc organiser les droits de protection des différents fichiers de façon cohérente avec ceux du serveur HTTP.

accès en lecture par défaut
pour les magiciens, gwd a besoin du droit d'accès en écriture pour les fichiers bases/cnt/actlog et bases/cnt/robot (si vous avez activé l'option -robot_xcl parameter)
et quand des modifications sont apportées, gwd a besoin de l'accès en écriture à bases/basename.lck, bases/basename.gwd/notes_link et bases/basename.gwd/patches

Créer ces fichiers et faire sudo chown _www filename a été suffisant sur un site OVH-VPS.

Ces problèmes d'accès sont enregistrés dans le fichier log de votre serveur HTTP auquel vous n'avez pas nécessairement accès (dans le cas de serveurs mutualisés par exemple).

L'accès aux fichiers de votre serveur peuvent aussi être contrôlés par un ensemble de fichiers .htaccess. La gestion de ce mécanisme n'est pas trivial et sujet à erreurs! L'exemple ci dessous s'applique pour une version 2.4 de Apache (les versions antérieures ont une syntaxe légèrement différente).

Options +FollowSymLinks permet l'utilisation de liens symboliques

Require all denied interdit l'accès à ce dossier pour tous les usagers. Require all granted permet l'accès à ce dossier pour tous les usagers.

AllowOverride AuthConfig
AuthType Basic
AuthName "Username/Password required"
AuthUserFile /Users/Name/SomeFolder/htfriends.auth
Require valid-user

permet l'accès à ce dossier aux utilisateurs fournissant un mot de passe valide défini dans le fichier htfriends.auth.

htpasswd /Users/Name/SomeFolder/htfriends.auth UserName provoque l'ajout d'un nouvel utilisateur dans ce fichier.

GeneWeb Manual

Download and install GeneWeb program under GNU/Linux, Mac OS X, Microsoft Windows, FreeBSD; on Mac OS X, Linux or Windows using Docker; or in CGI mode behind a web server.
Understand GeneWeb server, homonym, consanguinity.

Use and manage genealogical databases

Import Gedcom .ged or GeneWeb .gw files with gwsetup or in command-line.
Update datas (add/remove individuals and families), merge duplicates, type dates.
Use wikitext syntax, macros, keyboard shortcuts.
Clean, recover, rename, save, archive a database.
Merge and split multiples databases.

Technical annex

Personalize CSS, header and trailer, templates, lexicon and declension.
Configuration file .gwf (for templm), wizard notes, passwords for friends/wizards and access restrictions to databases.
Add images in notes, further remarks for experts.