Files and Directories of Geneweb

Jean Vaucher (sept 2010)

Index

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
http://www.geneweb.org/en/download.html

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 will be 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, next to "gw", as soon as we start using Geneweb.

We see the "gw" directory but "bases" is absent... it will be created as soon as we start using Geneweb. "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 will be the first page displayed]. "gwd" starts the program to access the database. "gwsetup" starts a different program which uses various other programs to create, parametrize, back-up or convert databases. The purpose of the other ".txt" files is evident.

Click here to see more detailled contents of the "gw" directory and the "bases" directory after a simple database called "BASE" has been created. There is a lot of stuff in "gw" including the main "gwd" program (2.2 MB) and 6 other utilities; but, at this point, we don't need to look further into this directory. 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". You only need to look further if you wish to add languages or create new templates.

Generally, an "advanced" user will deal 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. The configuration file "BASE.gwf" 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 a 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.
  • images" is where Geneweb keeps the standard photo for each individual
  • etc: is where user templates are placed
  • lang, src: is where user written HTML pages and images referenced in the Notes should be placed

Typical content of "bases"


In what follows, the Geneweb directory is called BASE stands for the name of your database and DIR stands for the path to the directory where Geneweb is installed. On my systems, BASE="jv1" and When you download and unpack the official "pre-compiled" Mac distribution, this is what you get:

Official MAC distribution
http://www.geneweb.org/en/download.html

All the geneweb software (programs, utilities, documentation and templates) are in the directory "gw". "gwd" and "gwsetup" are simple scripts which invoke programs in "gw" to allow us to work in stand-alone mode - using a web browser as the interface. "gwd" starts the main program used consult the database. "gwsetup" starts a different program which controls various utilities to CREATE, PARAMETRIZE, BACK-UP and CONVERT to and from GEDCOM format. These scripts also create the "bases" directory if necessary.

The progams started by "gwd" and "gwsetup" operate by opening INTERNET ports which to the Browser can send requests. "gwsetup" uses port 2316 to administer the database whereas "gwd" uses port 2317 for normal access.

Stand-alone use of Geneweb entails mainly clicking on links in web pages; but a look at the URL field shows what messages are sent to which port. Some examples will show how this works:

 
http://localhost:2316/en
will cause "gwsetup" to return its HOME page (in english)

http://localhost:2316/doc/en/start.htm
is a request for the "Getting Started" documentation (in English: "en")

http://localhost:2316/gwsetup?lang=fr;v=ged2gwb.htm
is a request to launch the "ged2gwd" utility to import a GEDCOM file and to use French (lang=fr) for the next page - asking for the file name.

http://localhost:2317/jv1
is a request to "gwd" (listening on port 2317) to access the HOME page for the database "jv1". In requests to "gwd", the first parameter always gives the name of the database.

http://localhost:2317/jv1?lang=no&m=NG&n=Vaucher&t=PN
Here some parameters are obscure; but it is a request for a listing of persons with lastname "Vaucher" in database "jv1" and the returned page should be in Norwegian (lang=no)
Usually, when working in stand-alone mode one will want to use both "gwd" and "gwsetup" and some distributions of Geneweb include a very useful script which does just that: GeneWeb.command. For example, Geneweb from http://www.gennerat.info/gw/gw50.dmg.zip (when expanded) gives the following with that command as the last item.

I find this directory structure to be overly complex. I prefer to use the GeneWeb.command with the flatter standard directory structure:

Since I have used the system, the "bases" directory has been created. This requires some minor chages to the command. My version can be found here.

Unix layout

In the UNIX WEB version, Geneweb is accessed by referencing a CGI script located in the enclosing directory directory. Two views of my set-up show that my CGI script is one level up from the "gw" and "bases" directories.

     
Note that I've kept an identical directory structure on both MAC and UNIX. This simplifies moving bases from one system to the other. The geneweb.cgi script is pretty simple. It invokes the same "gwd" program as before - but with the -cgi option, so that it doesn't use the 2317 port, and just executes on query.
	#!/bin/sh 
	cd GeneWeb/bases/
	exec ../gw/gwd -cgi -hd ../gw 2>/dev/null
Note that on the UNIX server, I don't use the stand-alone scripts "gw" or "gwsetup"; when required, I use the utilites (in the gw directory) directly; similarly "GeneWeb.command" is not needed and was not installed.

Browser request (Unix layout)

The parameters of all (gwd) requests to Geneweb on a Unix server are identical to those in stand-alone mode. The only difference between both situations is in the first part of the requestwhich denotes the target. In my case it is geneweb.cgi :
	http://www.iro.umontreal.ca/~vaucher/Genealogy/geneweb.cgi
Here is the request (from the browser) for all Vauchers in the database jv1 in both situations
 
Stand-Alone
http://localhost:2317/jv1?lang=no&m=NG&n=Vaucher&t=PN

UNIX Web server
http://www.iro.umontreal.ca/~vaucher/Genealogy/geneweb.cgi?b=jv1&lang=no&m=NG&n=Vaucher&t=PN