| Geneweb Secrets
Geneweb Directory Structure
Jean Vaucher (sept 2010)
Geneweb is a collection of programs, scripts, documentation and templates. The main program which handles user interaction with the databases is called gwd and it usually resides in a directory named gw along with with the other files of the Geneweb package. The databases are usually placed in a seperate directory called bases which is usually in the same directory as gw
When you download and unpack the official "pre-compiled" Mac distribution , this is what you get:
Official MAC distribution
The distribution is made up of the "gw" directory as well as some other files. "gwd"" and "gwsetup" are simple scripts which invoke the actual programs in "gw" to start operation in stand-alone mode - using the web browser as the interface [START.htm is the first page displayed]. "gwd" starts the program to access the database. "gwsetup" manages a set of utilities to create, parametrize, back-up or convert databases. The purpose of the other ".txt" files is evident.
What is missing is the bases directory where the Geneweb databases are kept. It will be created by the scripts - in the same directory as "gw"- as soon as we start using Geneweb.
Click here to see the contents of the "gw" and that of the "bases" directory after a simple database called "BASE" has been created. There is a lot of stuff in "gw" including the principal program "gwd" (2.2 MB) and 6 other utilities. The role of each utility is well described in the official documentation and the easiest way to use them is in stand-alone mode via "gwsetup". For our purpose, the contents of "gw" are not important.
Users are more concerned with files in the "bases" directory. For each database handled by Geneweb, there is a directory and a configuration file with standard extensions: ".gwb" and ".gwf" respectively. In our example: "BASE.gwb" and "BASE.gwf". The directory contains the genealogical data and the system indexes - coded in unreadable binary. "BASE.gwf" is a configuration file which keeps track of things like the passwords (if any), the default language and the template style to use.
|As we create other databases, customize them and users start accessing them, other files and directories appear in "bases". The figure at right, show typical contents. In particular, "lck" files are used to prevent simultaneous updates, "log" files are used to keep track of recent manipulations and statistics are kept in the "cnt" directory. Note that a second database (jv1) has been added with its "gwb" directory, and "gwf" and "lck" files.
Typical content of "bases"
Geneweb can operate either in stand-alone mode on your home computer or in CGI mode on a web server (or both if you have a server like Apache on your PC). The files in "gw" have identical names in all cases: the binary of the executable files (obviously) depends on the supporting hardware but the templates and documentation files are exactly the same. This goes further; in both modes, it is the same programs which get executed but the scripts which invoke them use different parameters depending on the mode.
Take, for example, the most important program, "gwd". In stand-alone mode,it executes as a permanent daemon waiting for requests on port "2317"; in CGI mode, it starts as a result of an HTTP request to the computer's web server (listening on the usual port #80). Geneweb requests name a CGI file (CGI files are not HTML to be sent back but rather code or scripts to be executed generating output which is then returned). The CGI file, often named geneweb.cgi, launches the same "gwd" program as before, but with the -cgi option, so that it doesn't use the #2317 port; instead, it gets its input from parameters, executes the query, generates the required output and quits.
The 3 main scripts: gwd (the script), gwsetup and the geneweb.cgi are relatively short but they may need to be altered depending on the directory structure of the installation. In particular, gwd (the program) needs to know the locations of the "gw" and the "bases" directories. This can be specified via the "-hd" and the "-bd" parameters. If a parameter is absent, gwd uses the current directory as a default. The documentation gives more details on gwd's parameters.
In my UNIX WEB version, I have put all Geneweb files (bases, gw and scripts) in a directory called Geneweb next to the geneweb.cgi script. I maintain an identical directory structure on both MAC and UNIX to simplify matters. Below, the left view shows that Geneweb and geneweb.cgi are both in the same directory. The right view shows the contents of GeneWeb.
The geneweb.cgi script is pretty simple. It sets the current directory to "bases" and invokes the same "gwd" program as before with the -cgi option and "-hd" specifying where "gw" is. "-bd" is not needed since we are executing in "bases".
#!/bin/sh cd GeneWeb/bases/ exec ../gw/gwd -cgi -hd ../gw 2>/dev/nullNote that on the UNIX server, I don't use the stand-alone scripts "gw" or "gwsetup"; I use the utilites (in the gw directory) directly.
I find this directory structure to be overly complex. I prefer to use the GeneWeb.command with the flatter standard directory structure:
This requires some minor changes to the command. My version can be found here.
The first part differs depending on the mode of operation (and the server location) but the last part is only determined by the service requested from Geneweb. In stand-alone mode, the URL to access the HOME page of database jv1 would be:
http://localhost:2317/jv1 or http://127.0.0.1:2317/jv1In server mode, the host name is more complicated, but the port number is omitted because web servers use port 80 by default. However, the path to the cgi script must be specified. In the case of the "jv1" base on my server at UMONTREAL, the URL for jv1 would be:
In these first examples, the common part at the end is minimal, just jv1. Below, we show the href part of a LINK in both modes for a more complex request: "list all individuals with surname "Smith" in database "base""
href="http://localhost:2317/base&m=NG&n=Smith&t=N" href="http://www.iro.umontreal.ca/~vaucher/Genealogy/geneweb.cgi?b=base&m=NG&n=Smith&t=N"Specifying the Geneweb server differs but the request parameters, at the end, are identical.
The example below show the URLs to display person #240 then move on to another (i=137)... maybe a child? The (encrypted) password has been tacked on to the base name giving "base_vxrbtfcjz and the language (French) is coded as "lang=fr"
- http://www.iro.umontreal..../geneweb.cgi?b=base_vxrbtfcjz;lang=fr;i=240 - http://www.iro.umontreal..../geneweb.cgi?b=base_vxrbtfcjz;lang=fr;i=137
We will see elsewhere that in user created pages, for example a directory of important people, it will be important to ensure that the standard request prefix is added to every URL which links back to Geneweb. To allow this, Geneweb provides as special MACRO written "%s", this expands to include the address of the server, the database name and any state information.
Updated: dec 2011