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

Official MAC distribution

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.
  • 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"
-- Back to the TOP --

Two modes of operation

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.

-- Back to the TOP --

Web server operation

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".

	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"; I use the utilites (in the gw directory) directly.
-- Back to the TOP --

Stand-alone operation

Usually, when working in stand-alone mode, one will want to use both gwd and gwsetup (active and listening on ports 2317 and 2316 respectively). gwd" to access databases and gwsetup to move to and from GEDCOM files. Some Geneweb distributions include a very useful script which launches both gwd and gwsetup: GeneWeb.command. This script doesn't seem to be in the standard distribution, but it is included in the distribution found at The directory hierarchy is different from what we have seen above but all the same files are there... PLUS GeneWeb.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:

This requires some minor changes to the command. My version can be found here.

-- Back to the TOP --

Geneweb-Browser interaction

Whether in server or stand-alone mode Geneweb interacts with users via browsers, like Firefox, Explorer or Safari. Geneweb generates HTML pages with LINKS to allow the user to navigate from one relative to another or to forms for search or update. The pages are generated in part from fixed templates but all LINKS are created dynamically to link back to the Geneweb server. The href fields are formatted as HTTP URLs with the general syntax:

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:

In 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""

Specifying the Geneweb server differs but the request parameters, at the end, are identical.

-- Back to the TOP --

Retaining state information

When using Geneweb, a user can select his preferred language (French, English, Spanish,...). He may also enter a password to allow display of recent information (as a friend) or modify the base (as a wizard). To pass this information from request to request, Geneweb adds it to its standard prefix for every URL generated in its pages. Thus when Geneweb receives a request, it will know the preferred language (and privileges) from the parameters and will reinsert this information in the HTML code it creates as an answer.

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

Generating the standard prefix: %s

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.

-- Back to the TOP --

Updated: dec 2011

Creative Commons License
GeneWeb Secrets by Jean Vaucher is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at