Difference between revisions of "CGI"

From GeneWeb
Jump to: navigation, search
(→‎The bases folder)
(→‎OVH-VPS (Ubuntu))
 
(184 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{DISPLAYTITLE:Install GeneWeb on a shared hosting account}}
+
{{DISPLAYTITLE:Install GeneWeb in CGI mode}}
−
{{languages|Server}}
+
{{languages|CGI}}
 +
{{toc right}}
  
−
A shared hosting account have some restrictions :
+
When daemon mode of GeneWeb is forbidden or cannot be activated, you must use '''CGI mode'''. It's mostly the case on a shared hosting account.  
−
* Daemon mode is forbidden, or cannot be activated. So you must use CGI mode.
+
−
* You must fit in the server environment : OS version, libraries, installed packages.
+
−
* The OS version is generally a stable version, but not the latest version.
+
  
−
[[Download]] a GeneWeb package
+
When running in CGI mode, GeneWeb sits behind a general purpose HTTP server such as Apache, and is launched by the server as a CGI command. As such, the first step in installing GeneWeb consists in verifying the operation of the HTTP server and of its CGI calling function.
−
* [[File:btn_lin.png]] made for recent Linux distribution
+
−
* [http://base.gennerat.net/pub/gw6.zip Geneweb distribution] made with Linux Debian Sarge, and currently running on 1&1 hosting.
+
  
−
== Directories and files ==
+
The second step is to install GeneWeb itself in a folder organisation adapted to your environment. You must indeed [[Download]] the GeneWeb version corresponding to your machine architecture (processor, 32/64 bits, OS).
−
The following applies to 1&1 hosting, and may differ on other hostings:
+
−
Under the root directory where CGI scripts may run, we have :
+
−
![[file:captur477.jpg]]
+
  
−
The directories :
+
== Verifying Web and CGI service ==
  
−
{| border="1" cellpadding="14" cellspacing="0"
+
Web service is verified by displaying from a web browser the content of index.html:
 +
<pre>
 +
(server):~#ls -al index.html
 +
-rwxr-xr-x  1 username usergroup    290 Nov 22 22:29 index.html
 +
</pre>
 +
The content of file {{c|index.html}} should be:
 +
<pre>
 +
<!DOCTYPE html>
 +
<html xmlns="http://www.w3.org/1999/xhtml">
 +
<body>
 +
This is a minimal index.html page
 +
</body>
 +
</html>
 +
</pre>
 +
Typing the following in your browser window:
 +
<pre>
 +
http://my_server_address/index.html
 +
</pre>
 +
should display:
 +
This is a minimal index.html page
  
−
|-
+
CGI service is verified by executing the file test-cgi.sh
−
|?||Beside the CGI-root directory
+
<pre>
−
|-
+
(server):~#cd cgi-bin
−
|mybases||The bases directory
+
(server):~/cgi-bin#ls -al test-cgi.sh
−
|-
+
-rwxr-xr-x  1 username usergroup    290 Nov 22 22:29 test-cgi.sh
−
|?||In the CGI-root directory
+
</pre>
−
|-
+
The content of {{c|test-cgi.sh}} should be:
−
|basesxg||An alternative bases directory
+
<pre>
−
|-
+
#!/bin/sh
−
|css||A copy of the gw/css directory. This directory is used by the Apache server.
+
echo 'Content-type: text/html'
−
|-
+
echo 
−
|gw||The gw directory of the Geneweb distribution
+
echo '<!DOCTYPE html>'
−
No change, except give the "exec" permission on the files gw/gwd, gw/gwsetup, and files used by gwsetup (gw/gwc*, gw/gwu,gw/consang, gw/update_nldb)
+
echo '<html xmlns="http://www.w3.org/1999/xhtml">'
−
The gwd.arg file is *empty*.
+
echo '<body>'
−
|-
+
echo 'This is a test for cgi commands'
−
|gwenv||The gw directory of the Geneweb-5 distribution
+
echo '</body>'
−
On this web site, we can easily switch between the 2 last versions of GeneWeb.
+
echo '</html>'
−
|-
+
</pre>
−
|igw||The images directory for Geneweb-5
+
−
|-
+
−
|images||A directory where copies of gw/images/gwback.jpg, gw/images/gwlogo_bas.png
+
−
|-
+
−
|pub||A directory where are readable copies of the CGI scripts (this website is a demo site) :
+
−
[http://base.gennerat.net/pub/gw5.cgi.txt launch Geneweb-5]
+
−
[http://base.gennerat.net/pub/gw6.cgi.txt launch Geneweb-6]
+
−
[http://base.gennerat.net/pub/issue6.cgi.txt check if Geneweb-6 can be launched]
+
−
|}
+
  
−
And the files :
+
Typing the following in your browser window:
 +
<pre>
 +
http://my_server_address/cgi-bin/test-cgi.sh
 +
</pre>
 +
should display:
 +
This is a test for cgi commands
  
−
{| border="1" cellpadding="10" cellspacing="0"
+
Note the ownership and read/write/execute characteristics if these files. See [[#Access rights and protection]] for a more detailed analysis.
 +
 
 +
Depending on your hosting service, the location of these files in the system root (where you end up if you execute {{c|cd}}), web_root and cgi-bin folders may vary (see [[#Example folder organisations|Example folder organisations]]).
 +
 
 +
== The cgi-bin folder ==
 +
 
 +
The {{c|cgi-bin}} folder contains the cgi commands launching the gwd server software for each request from a browser client.
 +
 
 +
{{arbre début}}
 +
*
 +
** {{d}} cgi-bin: The folder containing CGI executables.
 +
*** {{d}} gwd.sh
 +
*** {{branche finale}}{{d}} test-cgi.sh
 +
{{arbre fin}}
 +
 
 +
The content of {{c|gwd.sh}} is:
 +
<syntaxhighlight lang="bash">
 +
(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  2>./gwd.log
 +
</syntaxhighlight>
 +
 
 +
The {{c|gwd.sh}} file is a shell script that launches {{c|gwd}} with the appropriate parameters:
 +
 
 +
It contains the following definitions:
 +
* DIR points to the {{c|gw}} folder holding the various executables files of GeneWeb (see [[distribution|GeneWeb distribution]]).
 +
* BASE_DIR points to the folder holding your genealogy bases (see [[bases|GeneWeb-Bases folder]]).
 +
: Details of these two pathnames may vary according to your hosting service and your folder organisation (see [[#Example folder organisations]]).
 +
* OPTIONS holds the set of start parameters for '''gwd''', see [[gwd]] for details.
 +
 
 +
You may maintain in this folder several {{c|gwd-xx.sh}} files pointing to their respective {{c|DIR}} location holding different versions of GeneWeb, or starting with a different set of {{c|OPTIONS}} parameters.
 +
 
 +
The set of '''[[gwd]]''' start parameters can also be provided through a file named {{c|gwd.arg}} sitting in the {{c|gw}} forder. Note that in this file, the parameter and its value are on two separate lines.
 +
 
 +
<pre>
 +
(server):~ > cat /home/geneweb-distribution/gw/gwd.arg
 +
-cgi
 +
-bd
 +
~/bases
 +
-hd
 +
./
 +
-robot_xcl
 +
19,60
 +
-allowed_tags
 +
./tags.txt
 +
(server):~ >
 +
</pre>
 +
 
 +
== The distribution and bases folders ==
 +
 
 +
The remainder of the folder organisation follows the same structure as in the classical install, with one or more  '''[[distribution|GeneWeb distribution]]''', and the '''[[bases|GeneWeb-Bases folder]]''' containing one or several genealogy bases.
 +
 
 +
== Example folder organisations ==
 +
 
 +
The following folders organisation have been tested on several hosting services:
 +
{|
 +
|- style="vertical-align:top;"
 +
|
 +
=== OVH-Webm ===
 +
 
 +
{{arbre début}}
 +
* {{d}} www
 +
** {{d}} cgi-bin
 +
***{{f}} gwd.sh
 +
***{{branche finale}}{{f}}  test-cgi.sh
 +
** {{d}} geneweb-distrib
 +
** {{d}} geneweb-bases
 +
** {{f}} gw -> geneweb-distrib/gw
 +
** {{f}} index.html
 +
{{arbre fin}}
 +
||
 +
=== OVH-VPS ===
 +
 
 +
{{arbre début}}
 +
* {{d}} /
 +
** {{d}} root
 +
*** {{d}} geneweb-distrib
 +
*** {{branche finale}}{{d}} geneweb-bases
 +
** {{d}} usr
 +
*** {{branche finale}}{{d}} lib
 +
**** {{branche finale}}{{d}} cgi-bin
 +
***** {{f}} gwd.sh
 +
***** {{branche finale}}{{f}}  test-cgi.sh
 +
** {{d}} var
 +
*** {{d}} www
 +
*** {{branche finale}}{{d}} html
 +
**** {{f}} gw -> /root/geneweb-distrib/gw
 +
**** {{branche finale}}{{f}} index.html
 +
{{arbre fin}}
 +
Verified with Ubuntu on 01/02/2022
 +
||
 +
 
 +
=== 1&1 ===
 +
 
 +
{{arbre début}}
 +
* {{d}} home
 +
** {{d}} cgi-bin
 +
***{{f}} gwd.sh
 +
***{{branche finale}}{{f}}  test-cgi.sh
 +
** {{d}} geneweb-distrib
 +
** {{d}} geneweb-bases
 +
** {{f}} gw -> geneweb-distrib/gw
 +
** {{f}} index.html
 +
{{arbre fin}}
 +
||
 +
=== TuxFamily.org ===
 +
{{arbre début}}
 +
* {{d}} .../htdocs
 +
** {{d}} gw
 +
*** {{d}} consang
 +
*** {{d}} etc
 +
*** {{e}} gwc
 +
*** {{e}} gwd
 +
*** {{e}} gwu
 +
*** {{f}} .htaccess
 +
*** {{d}} images
 +
*** {{d}} lang
 +
*** {{f}} only.txt
 +
*** {{branche finale}}{{f}}  tags.txt
 +
** {{s}} gwd
 +
** {{f}} .htaccess
 +
{{arbre fin}}
  
−
|issue6.cgi||A test script which
 
−
- displays information about the environment in the server
 
−
- checks the gwd binary file : size and md5sum
 
−
|-
 
−
|issue5.cgi||The same script, but for the GeneWeb-5 version
 
−
|-
 
−
|gw6.cgi ||The CGI script which launches GenWeb-6
 
−
|-
 
−
|gw5.cgi ||The CGI script which launches GenWeb-5
 
 
|}
 
|}
  
−
== Parameters of the CGI script ==
+
== Connecting style files ==
−
<syntaxhighlight lang="PHP">
+
 
 +
In a hosted CGI server environment, the style ({{c|.css}}) and javascript ({{c|.js}}) files are sent to your browser by the HTTP server (Apache) rather that '''gwd'''. You therefore have to install at the web_root a link to the repository holding the style files.
 +
 
 +
The example below is taken from a OVH-VPS hosted server.
 +
 
 +
<pre>
 +
root@vps265730:/var/www/html# 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/html#
 +
</pre>
 +
 
 +
In order to instruct '''gwd''' to use this path, you must add in your {{c|.gwf}} configuration file the following variable:
 +
  static_path=/gw/etc/
 +
<!-- Note the leading {{c|..}} due to the fact that the script launching '''gwd''' executes one level below the web_root of your server.
 +
<nowiki>http://server_address/cgi-bin/gwd-7.00.sh</nowiki> -->
 +
 
 +
The use of links assumes that your Apache server is properly configured, allowing sim links (FollowSymLinks).
 +
Experience shows that such configuration is touchy and sometimes defeated by some service provider restrictions. In such cases, copying the requested files to the appropriate location may be an alternative.
 +
 
 +
In the TuxFamily.org example above, links are not used. The value of {{c|static_path}} is empty.
 +
 
 +
== 1&1 hosting, GeneWeb 5 and 6 ==
 +
(Kept here for historical reasons)
 +
 
 +
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'''
 +
[[File:Captur477.jpg|thumb|right|Files and directories on 1&1.]]
 +
 
 +
{{arbre début}}
 +
*
 +
** {{d}} mybases: The bases directory, beside the CGI-root directory.
 +
*** {{d}} mybases.gwb
 +
*** {{d}} cnt
 +
*** {{branche finale}} {{d}} images
 +
** {{branche finale}} {{d}} root: The CGI-root directory.
 +
*** {{d}} basesxg: An alternative bases directory.
 +
*** {{d}} css: A copy of the gw/css directory. This directory is used by the Apache server.
 +
*** {{d}} gw: The gw directory of the GeneWeb distribution.
 +
*** {{d}} gwenv: The gw directory of the Geneweb-5 distribution.
 +
*** {{d}} igw: The images directory for Geneweb-5.
 +
*** {{d}} images: A directory with copies of {{c|gw/images/gwback.jpg}} and {{c|gw/images/gwlogo_bas.png}}
 +
*** {{d}} pub: A directory where are readable copies of the CGI scripts (this website is a demo site).
 +
*** {{f}} [http://base.gennerat.net/pub/gw6.cgi.txt gw6.cgi]: The CGI script which launches GenWeb-6.
 +
*** {{f}} [http://base.gennerat.net/pub/gw5.cgi.txt gw5.cgi]: The CGI script which launches GenWeb-5.
 +
*** {{f}} [http://base.gennerat.net/pub/issue6.cgi.txt issue6.cgi]: A test script which displays information about the environment of the server and checks size and md5sum for the gwd binary file.
 +
*** {{branche finale}} {{f}} issue5.cgi: The same script, but for the GeneWeb-5 version
 +
{{arbre fin}}
 +
 
 +
You need the “exec” permission on the files {{c|gw/gwd}}, {{c|gw/gwsetup}}, and files used by gwsetup (gw/gwc*, gw/gwu,gw/consang, gw/update_nldb). The {{c|gwd.arg}} file is empty.
 +
 
 +
The databases folder {{c|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:
 +
{|
 +
|-
 +
| <syntaxhighlight lang="bash">
 
PWD=$(pwd)
 
PWD=$(pwd)
 
LNG="fr"
 
LNG="fr"
Line 72: Line 260:
 
DAEMON=$GENEWEBSHARE/gwd
 
DAEMON=$GENEWEBSHARE/gwd
 
LOGFILE=$GENEWEBDB/gw.log
 
LOGFILE=$GENEWEBDB/gw.log
−
</syntaxhighlight>
+
</syntaxhighlight> || <syntaxhighlight lang="html5">
 +
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.</syntaxhighlight>
 +
|}
 +
 
 +
Note that although called DAEMON, gwd does not run in {{c|-daemon}} mode but in {{c|-cgi}} mode.
  
−
Main settings :
+
Be carefull when using a log file, its size can increase quickly, don’t forget to delete it from time to time.
−
* 1 get the CGI working directory
+
−
* 2-7 set the main parameters
+
−
* 5 $GENEWEBDB does not need to be accessed by the HTTP server.
+
−
It must be protected either by a .htaccess file, either by a location out of the HTTP server scope.
+
−
* 7 a log file is useful when there are problems, but do not forget to delete it after downloading.
+
  
−
<syntaxhighlight lang="PHP">
+
<syntaxhighlight lang="bash">
 
OPTIONS="-blang -robot_xcl 40,70 -max_clients 15 -conn_tmout 120 -min_disp_req 30 -images_url http://myserver.net/gw/images"
 
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
 
# -allowed_tags $GENEWEBDB/tags.txt
Line 88: Line 281:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Options and launching
+
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.
  
−
* 1 OPTIONS
+
=== Windows ===
−
{|  border="1" cellpadding="10" cellspacing="0"
+
Under Windows calling a CGI script using batch and cmd.exe can be tricky. An alternative is to directly call a copy of {{c|gwd.exe}} with its arguments file {{c|gwd.arg}} in Apache /cgi-bin/ directory file.
  
−
|-
+
Gwd will work behind Apache calling http://localhost/cgi-bin/gwd.exe.
−
| -robot_xcl||to protect your data from HTTrack or WebSite Extractor
+
{{arbre début}}
−
|-
+
* {{d}} cgi-bin
−
| -conn_tmout||for statistics on the bottom line
+
** {{f}} gwd.exe
−
|-
+
** {{branche finale}} {{f}} gwd.arg
−
| -images_url||icons and images are not sent by GeneWeb, but par your HTTP server (not CGI).
+
{{arbre fin}}
−
|-
+
−
| -allowed_tags||another useful option, if you use HTML tags not in default_good_tag_list
+
−
|}
+
−
* 3 cd $GENEWEBSHARE. I am not sure it is really needed.
+
−
* 4 launch GeneWeb
+
  
−
= An alternative installation on 1&1 =
+
Edit {{c|gwd.arg}} to point your local GeneWeb installation, for example if it is {{c|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
  
−
== Some general comments ==
+
Problems to solve:
 +
- Portrait (all images with m=IMH) are not shown or are corrupted ([https://github.com/geneanet/geneweb/issues/103 #103]).
 +
- Minor problems in 7.00 with loading of new .css/.js files, specialy for templm ([https://github.com/geneanet/geneweb/issues/356 #356]).
  
−
Installing GeneWeb on a remote shared server is a little bit (but not that much) more complex than on a personal computer.
+
'''Images missing'''
−
GeneWeb is a totally self contained package, therefore does not depend on additional libraires.
+
−
On a server, GeneWeb cannot execute in ''daemon'' mode (Unix aficionados will understand), and must be launched in CGI mode. To that extent, a server based installation requires prior installation of a (standard) HTTP server (typically Apache), access to the CGI repository of this server and some control over the access rights to the various folders and files. Installing or verifying your HTTP server is not part of this discussion.
+
  
−
A second restriction of GeneWeb on a server is that [[gwsetup]] cannot be used (mainly for security reasons). It is therefore necessary to use [[man|command lines]] on the remote server through a {{c|ssh}} window or any other remote access tool of your choice.  
+
{{c|-images_dir}} parameter create links to local image files like {{c|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 {{c|-images_url}} parameter so that gwd uses relatives paths for images and to create a virtual directory in your httpd server.
−
It is also necessary to have access to a upload mechanism from your personal machine to the server through classical Unix/Linux command lines, or through a {{c|ftp}} client such as Filezilla. A section below will describe in detail a shell script performing upload to the server of a complete fresh copy of a base sitting on your personal computer.
+
  
−
== Folders and files ==
+
In gwd.arg, modify:
 +
<pre>
 +
-images_url
 +
/images
 +
</pre>
  
−
The first important file for your installation is the welcome page of your HTTP server, by default {{c|index.html}} sitting at the root of your server. After personalization of this welcome page, you should verify that you can view it by typing the name (or IP address) of your server in the URL window of your browser.
+
If you use Apache, edit httpd.conf to have those lines, then restart httpd.exe:
 +
<pre>
 +
LoadModule access_compat_module modules/mod_access_compat.so
 +
LoadModule alias_module modules/mod_alias.so
  
−
The second important item is the CGI folder containing the executable files invoqued  through URLs.
+
Alias /images " C:\Program Files (x86)\geneweb\gw\images"
−
This folder is typically called {{c|cgi-bin}} and also sits at the root of your HTTP server.
+
−
If this folder contains the following executable file named {{c|test-cgi.sh}}:
+
−
#!/bin/sh
+
−
echo '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"  '
+
−
echo '  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">  '
+
−
echo '<html xmlns="http://www.w3.org/1999/xhtml">  '
+
−
echo '<body>'
+
−
echo 'This is a test for cgi commands'
+
−
echo '</body>'
+
−
echo '</html>'
+
−
then typing in the URL window of your browser the following text
+
−
your_server_name/cgi-bin/test-cgi.sh
+
−
should result in the text '''This is a test for cgi commands''' appearing in your browser window.
+
  
−
You must reach this level of functionality to proceed.
+
<Directory " C:\Program Files (x86)\geneweb\gw\images">
 +
  Options None
 +
  AllowOverride All
 +
  Order allow,deny
 +
  Allow from all
 +
</Directory>
 +
</pre>
  
−
At the root of your server, create two additional folders {{c|GeneWeb}} and {{c|Documents}}.
+
== Script to upload a copy of a base ==
−
* The first folder will contain all GeneWeb related files (binaries, bases, images, ...) and need not or should not be accessible with the HTTP server,
+
−
* The second folder will contain any other documents that you may want to share with the visitors of your site.
+
  
−
At this time, we have the following situation:
+
The files below are supplied to experienced users knowledgeable with shell scripts and the subtelties of Linix (Sorry, not available for Windows). "Use at your own risk" is the traditionnal caveat! Report for errors or improvements are indeed welcome.
−
<pre>
+
−
(uiserver):u72332903:~ > cd
+
−
(uiserver):u72332903:~ > ls -al
+
−
total 554088
+
−
drwx---r-t 23 u72332903 ftpusers      4096 Oct  7 06:58 .
+
−
drwxr-xr-t  7 root      root          4096 Oct 23 00:21 ..
+
−
-rw-------  1 u72332903 ftpusers      8319 Oct 10 09:30 .bash_history
+
−
drwxr-xr-x  3 u72332903 ftpusers      4096 Sep 24 21:24 Documents
+
−
drwxr-xr-x 10 u72332903 ftpusers      4096 Sep 24 21:24 GeneWeb
+
−
drwxr-xr-x  3 u72332903 ftpusers      4096 Oct  7 06:58 cgi-bin
+
−
-rw-r--r--  1 u72332903 ftpusers      3535 May 22 14:30 index.html
+
−
-rw-r--r--  1 u72332903 ftpusers        27 Nov  6  2013 robots.txt
+
−
(uiserver):u72332903:~ >
+
−
</pre>
+
  
−
=== The GeneWeb folder ===
+
The script {{c|[[base-upld|base-upload.sh]]}} ([http://download.tuxfamily.org/geneweb/wiki/base-upload.sh download it]) takes a {{c|base_name}} as an argument, and optionally {{c|images}} or {{c|src}}. It uploads a fresh base on your server, or a fresh copy of the {{c|images/base}} or {{c|src/base}} folders. It performs the following steps:
  
−
The GeneWeb folder contains one or more versions of GeneWeb ({{c|geneweb-6.08}} and {{c|geneweb-7.00}} in our example), and the {{c|bases}} folder.
+
* creates a fresh base.gw file from the base on your personal computer.
 +
* extracts a listing of the content of {{c|bases/images/base}} {{c|bases/src/base}} and {{c|bases/src/base/images}} in three {{c|ls-xxx.txt}} files.
 +
* creates a {{c|remote.sh}} file (see {{c|[[remote-base|remote-base.sh]]}} or {{c|[[remote-files|remote-files.sh]]}}) depending on the second parameter.
 +
* creates a tar file containing {{c|base.gw}}, {{c|history}}, {{c|remote.sh}} and the three {{c|ls-*.txt}} files above.
 +
* sends the tar file to the remote server.
 +
* triggers on the remote server unfolding of the tar file and execution of the {{c|remote.sh}} script. Depending on the availability of {{c|/usr/bin/mail}} on your server, the result of this remote execution can be a mail containing the {{c|remote.log}} and three diff between images folders.
  
−
Each {{c|geneweb-x.yy}} folder has the same structure, containing a copy of the {{c|distribution}} folder resulting from the compilation of GeneWeb. You can upload with {{c|ftp}} this folder, or you can compile yourself GeneWeb directly on your server, but this necessitates the installation of Ocaml and camlp5 (see [[Ocaml]].
+
This procedure saves the previous folder of the base or its images and src folders with a "yyyy-mm-dd-hh:mm:ss" date tag. As time progresses, you may want to clean-up this accumulation of saves.
  
−
<pre>
+
When uploading a base, the {{c|remote.sh}} shell script is executed on your remote server, and installs your base or its images at the proper location (according to the overall set-up described here).
−
(uiserver):u72332903:~/GeneWeb > cd geneweb-6.08
+
−
(uiserver):u72332903:~/GeneWeb/geneweb-6.08 > ls -al
+
−
total 204
+
−
drwx---r-x  3 u72332903 ftpusers    82 Jan 12  2015 .
+
−
drwxr-xr-x 10 u72332903 ftpusers  4096 Sep 24 21:24 ..
+
−
-rw----r--  1 u72332903 ftpusers 160302 Jan 12  2015 CHANGES.txt
+
−
-rw----r--  1 u72332903 ftpusers  18007 Jan 12  2015 LICENSE.txt
+
−
-rw----r--  1 u72332903 ftpusers  10345 Jan 12  2015 START.htm
+
−
drwx---r-x  8 u72332903 ftpusers  4096 Dec 17  2014 gw
+
−
-rw---r-x 1 u72332903 ftpusers  108 Dec 17  2014 gwd.command
+
−
-rw---r-x 1 u72332903 ftpusers  1117 Dec 17  2014 gwsetup.command
+
−
(uiserver):u72332903:~/GeneWeb/geneweb-6.08 >
+
−
(uiserver):u72332903:~/GeneWeb/geneweb-6.08 > cd gw
+
−
(uiserver):u72332903:~/GeneWeb/geneweb-6.08/gw > ls -al
+
−
total 13268
+
−
drwx---r-x  8 u72332903 ftpusers    4096 Dec 17  2014 .
+
−
drwx---r-x  3 u72332903 ftpusers      82 Jan 12  2015 ..
+
−
-rw----r--  1 u72332903 ftpusers  15280 Jan 12  2015 a.gwf
+
−
-rwx---r-x  1 u72332903 ftpusers  529764 Jan 12  2015 consang
+
−
drwx---r-x 12 u72332903 ftpusers    4096 Dec  2  2014 etc
+
−
-rwx---r-x  1 u72332903 ftpusers 1182404 Jan 12  2015 ged2gwb
+
−
-rwx---r-x  1 u72332903 ftpusers 1200900 Jan 12  2015 ged2gwb2
+
−
-rwx---r-x  1 u72332903 ftpusers  552100 Jan 12  2015 gwb2ged
+
−
-rwx---r-x  1 u72332903 ftpusers  631844 Jan 12  2015 gwc
+
−
-rwx---r-x  1 u72332903 ftpusers  861434 Jan 12  2015 gwc1
+
−
-rwx---r-x  1 u72332903 ftpusers  630084 Jan 12  2015 gwc2
+
−
-rwx---r-x  1 u72332903 ftpusers 2422372 Jan 12  2015 gwd
+
−
-rw----r--  1 u72332903 ftpusers      12 Jan 12  2015 gwd.arg
+
−
-rw----r--  1 u72332903 ftpusers      0 Jan 12  2015 gwd.log
+
−
-rw----r--  1 u72332903 ftpusers      42 Oct 10  2014 gwd.xcl
+
−
-rw----r--  1 u72332903 ftpusers 3851203 Jan 12  2015 gwdl.log
+
−
-rwx---r-x  1 u72332903 ftpusers  358308 Jan 12  2015 gwsetup
+
−
drwx---r-x  3 u72332903 ftpusers      68 Jan  3  2015 gwtp_tmp
+
−
-rwx---r-x  1 u72332903 ftpusers  589028 Jan 12  2015 gwu
+
−
drwx---r-x  3 u72332903 ftpusers    4096 Nov 20  2014 images
+
−
drwx---r-x  2 u72332903 ftpusers    140 Jan 12  2015 lang
+
−
drwx---r-x  2 u72332903 ftpusers      6 Sep 24  2014 old
+
−
-rw----r--  1 u72332903 ftpusers      10 Jan 12  2015 only.txt
+
−
drwx---r-x  3 u72332903 ftpusers      33 Sep 24  2014 setup
+
−
-rw----r--  1 u72332903 ftpusers    104 Dec 17  2014 tags.txt
+
−
-rwx---r-x  1 u72332903 ftpusers  497028 Jan 12  2015 update_nldb
+
−
(uiserver):u72332903:~/GeneWeb/geneweb-6.08/gw >
+
−
</pre>
+
  
−
=== The cgi folder ===
+
If you launch the {{c|base-upload.sh}} script with the additionnal parameter {{c|images}} or {{c|src}} the script {{c|[[remote-files|remote-files.sh]]}} is executed on your remote server, and installs the {{c|images}} or {{c|src/images}} folders for your base at the proper location (according to the overall set-up described here).
  
−
The {{c|cgi-bin}} folder contains the cgi commands launching the gwd server software for each request from a browser client.
+
Depending on the size of your images folders, and on the number of new images requiring upload, you may prefer to upload images individually with your preferred {{c|ftp}} client rather than doing the bulk upload proposed here. Remember that the base upload script reports a form of comparison between the images folders on your personal computer and your server.
  
−
<pre>
+
== Debugging your remote server ==
−
(uiserver):u72332903:~ > cd cgi-bin/
+
−
(uiserver):u72332903:~/cgi-bin > ls -al
+
−
total 144
+
−
drwxr-xr-x  3 u72332903 ftpusers  4096 Oct  7 06:58 .
+
−
drwx---r-t 23 u72332903 ftpusers  4096 Oct  7 06:58 ..
+
−
lrwxrwxrwx  1 u72332903 ftpusers    8 Jan 12  2015 Gwd -> Gwd-7.00
+
−
-rwxr-xr-x  1 u72332903 ftpusers  183 Oct 10  2014 Gwd-6.08
+
−
-rwx---r-x  1 u72332903 ftpusers  183 Jan 12  2015 Gwd-7.00
+
−
-rwx---r-x  1 u72332903 ftpusers  183 Jan 15  2015 test-cgi.sh
+
−
(uiserver):u72332903:~/cgi-bin >
+
−
</pre>
+
  
−
{{c|Gwd}} is a symbolic link to the current version of GeneWeb (7.00 in our example).
+
Debugging your remote server may be tricky, but some systematic approach and several tools will help.
 +
* Verify first that your '''HTTP server''' works properly. This is achieved by typing {{c|your_server_name}} in the URL window of your browser which should return the content of {{c|index.html}}.
 +
* Verify that the '''cgi''' mechanism works. This is achieved by typing {{c|your_server_name/cgi-bin/test-cgi.sh}} as seen above (see [[#Folders and files]]).
 +
: If your server returns a "Internal server error", several hypothesis should be examined:
 +
:* Your script test-cgi.sh does not work properly. Run it directly on a terminal window by typing {{c|./test-cgi.sh}} (see  [[#Folders and files]]).
 +
:* Your server accepts only files with extension {{c|.cgi}}. Rename {{c|test-cgi.sh}} into {{c|test-cgi.cgi}} and try again.
 +
:* The first two lines returned by your test-cgi.sh script are not exactly as shown (the second one should be a blank line, Note also that "Content-type text/html\n\n" did not work in my tests).
 +
:* You also may want to verify that your "End-of-Lines" are correct for your server environment. Remember that there are three different such {{c|EOL}} encoding for Windows, Mac, and Linux!!
 +
:* Examine the HTTP server log file on your server by typing:
 +
:: {{c|tail /var/log/apache2/access.log}} (location in OVH-VPS configuration)
 +
:: your environment may store access logs somewhere else, but this is the most likely place. You may discover this place by typing {{c|find / -name access.log -print}}.
 +
:: Examination of the log file may give you a hint as to the nature of your problem.
 +
* Another typical issue is that of '''ownership''' of the various files associated with GeneWeb. In the case described here, ownership is {{c|user}} and group ownership is {{c|ftpusers}}. Depending on the specific method you have used to install GeneWeb, this may vary. Some discussions on the Yahoo! group forum about GeneWeb mentions ''geneweb'' for group ownership!
 +
* You may also want to look at the '''gwd log file''' if your GeneWeb server works only partially (welcome page is ok, but other pages do not work properly). This log file is specified in the gwd launch command. In our example, it sits at {{c|$DIR/gwd.log}} where $DIR depends on the specific version of GeneWeb you are currently running (see details in [[#The cgi-bin folder]] section above).
 +
* You may end up in a situation where GeneWeb works only partially, in particular it may miss some css style sheet or JavaScript files. One way of debugging this kind of problem consists in exploring the HTML source file produced by GeneWeb (your browser offers this capability addressed to "developers"). Is such source files, you will find reference to css and JavaScript files whose source should appear in your browser if you click on the link. In case of bad configuration, you will obtain an error messages such as "File not found" or "You do not have permission"…
 +
: Remember that some of the files needed for proper display are fetched by the HTTP server rather than by GeneWeb.
  
−
Each of the {{c|gwd-x.yy}} file is a shell script that launches {{c|gwd}} with the appropriate parameters:
+
== Access rights and protections ==
 +
In CGI mode, gwd runs behind a standard HTTP server, typically Apache. As such, the owner of the gwd process is the owner of the HTTP server. For instance, with Apache, this owner is defined in the http.conf file and its default value is set to {{c|user: _www}} and {{c|group: —www}}. When running within a hosting environment, such as 1&1, you typically do not have access to this parameter. You must therefore organise the protection level of the various folders involved with GeneWeb appropriately:
 +
* read access is usually allowed by default
 +
* for wizards, gwd needs write access to {{c|bases/cnt/actlog}}, {{c|bases/cnt/robot}} (if you have activated the -robot_xcl parameter)
 +
* and when modifications are performed, gwd needs write access to {{c|bases/basename.lck}}, {{c|bases/basename.gwd/notes_link}} and to {{c|bases/basename.gwd/patches}}
 +
Creating those files, and doing a {{c|sudo chown _www filename}} seems to be sufficient.
  
−
#!/bin/sh
+
Access problems are reported in the HTTP error log file, unfortunately not always available in the case of shared hosting services!!
−
DIR=~/GeneWeb/geneweb-6.08/gw
+
 
−
BASE_DIR=~/GeneWeb/bases
+
Access to various files through your hosted HTTP server is also controlled by your hosting service and through .htaccess files spread across your folders. Managing a coherent set of .htaccess files is not trivial and error prone!! The examples below apply to Apache version 2.4 only (earlier versions have different directives!!).
−
OPTIONS="-robot_xcl 19,60 -allowed_tags ./tags.txt -hd ./"
+
 
−
cd $DIR
+
{{c|Options +FollowSymLinks}} should allow following symbolic links
−
./gwd -cgi  $OPTIONS  -bd ../../bases  > ./gwd.log 2>&1
+
  
−
To change your server to another version of GeneWeb (7.00 for instance), you should do the following:
+
{{c|Require all denied}} prevents access to this folder to all users.
 +
{{c|Require all granted}} allows access to this folder to all users.
  
−
  cd cgi-bin
+
  AllowOverride AuthConfig
−
  rm -f Gwd
+
  AuthType Basic
−
  ln -s Gwd-7.00 Gwd
+
  AuthName "Username/Password required"
 +
AuthUserFile /Users/Name/SomeFolder/htfriends.auth
 +
Require valid-user
 +
should restrict access to this folder to users supplying a valid password as defined by the {{c|htfriends.auth}} file.  
  
−
=== The bases folder ===
+
{{c|htpasswd /Users/Name/SomeFolder/htfriends.auth UserName}} will trigger the process to add a new user to the list.
  
−
The base folder should contain the same information structure as in the case of installation on a personal computer:
 
−
* one or several basename.gwb folders
 
−
* '''cnt''' containing access count data
 
−
* '''etc''' containing template text files used in priority over the generic {{c|gw/etc}} files (see [[header]])
 
−
* '''images''' containing for each base photos associated with each person ({{c|first_name.occ.last_name.jpg}})
 
−
* '''src''' containing for each base text files and image files inserted in notes with the m=SRC command (see [[gwd|gwd commands]])
 
  
−
[[File:Folder-Bases.png|thumb|320px|right|Folder structure for GeneWeb Bases (Genealogy data).]]
+
{{manual}}
  
−
== A script to upload a copy of a base ==
+
[[Category:Manual]]

Latest revision as of 08:17, 3 January 2022

150px-Geographylogo svg.png Language: English • français

When daemon mode of GeneWeb is forbidden or cannot be activated, you must use CGI mode. It's mostly the case on a shared hosting account.

When running in CGI mode, GeneWeb sits behind a general purpose HTTP server such as Apache, and is launched by the server as a CGI command. As such, the first step in installing GeneWeb consists in verifying the operation of the HTTP server and of its CGI calling function.

The second step is to install GeneWeb itself in a folder organisation adapted to your environment. You must indeed Download the GeneWeb version corresponding to your machine architecture (processor, 32/64 bits, OS).

Verifying Web and CGI service

Web service is verified by displaying from a web browser the content of index.html: 

(server):~#ls -al index.html
-rwxr-xr-x  1 username usergroup    290 Nov 22 22:29 index.html

The content of file index.html should be: 

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<body>
This is a minimal index.html page
</body>
</html>

Typing the following in your browser window: 

http://my_server_address/index.html

should display: 

This is a minimal index.html page

CGI service is verified by executing the file 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

The content of test-cgi.sh should be: 

#!/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>'

Typing the following in your browser window: 

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

should display: 

This is a test for cgi commands

Note the ownership and read/write/execute characteristics if these files. See #Access rights and protection for a more detailed analysis.

Depending on your hosting service, the location of these files in the system root (where you end up if you execute cd), web_root and cgi-bin folders may vary (see Example folder organisations).

The cgi-bin folder

The cgi-bin folder contains the cgi commands launching the gwd server software for each request from a browser client.

    • directory cgi-bin: The folder containing CGI executables.
      • directory gwd.sh
      • directory test-cgi.sh

The content of gwd.sh is: 

(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   2>./gwd.log

The gwd.sh file is a shell script that launches gwd with the appropriate parameters:

It contains the following definitions:

Details of these two pathnames may vary according to your hosting service and your folder organisation (see #Example folder organisations).
  • OPTIONS holds the set of start parameters for gwd, see gwd for details.

You may maintain in this folder several gwd-xx.sh files pointing to their respective DIR location holding different versions of GeneWeb, or starting with a different set of OPTIONS parameters.

The set of gwd start parameters can also be provided through a file named gwd.arg sitting in the gw forder. Note that in this file, the parameter and its value are on two separate lines. 

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

The distribution and bases folders

The remainder of the folder organisation follows the same structure as in the classical install, with one or more GeneWeb distribution, and the GeneWeb-Bases folder containing one or several genealogy bases.

Example folder organisations

The following folders organisation have been tested on several hosting services:

OVH-Webm

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

OVH-VPS

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

Verified with Ubuntu on 01/02/2022

1&1

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

TuxFamily.org

  • directory .../htdocs
    • directory gw
      • directory consang
      • directory etc
      • alt exe gwc
      • alt exe gwd
      • alt exe gwu
      • file .htaccess
      • directory images
      • directory lang
      • file only.txt
      • file tags.txt
    • script file gwd
    • file .htaccess

Connecting style files

In a hosted CGI server environment, the style (.css) and javascript (.js) files are sent to your browser by the HTTP server (Apache) rather that gwd. You therefore have to install at the web_root a link to the repository holding the style files.

The example below is taken from a OVH-VPS hosted server. 

root@vps265730:/var/www/html# 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/html#

In order to instruct gwd to use this path, you must add in your .gwf configuration file the following variable: 

 static_path=/gw/etc/

The use of links assumes that your Apache server is properly configured, allowing sim links (FollowSymLinks). Experience shows that such configuration is touchy and sometimes defeated by some service provider restrictions. In such cases, copying the requested files to the appropriate location may be an alternative.

In the TuxFamily.org example above, links are not used. The value of static_path is empty.

1&1 hosting, GeneWeb 5 and 6

(Kept here for historical reasons)

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

  • directory cgi-bin
    • file gwd.exe
    • file 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 to upload a copy of a base

The files below are supplied to experienced users knowledgeable with shell scripts and the subtelties of Linix (Sorry, not available for Windows). "Use at your own risk" is the traditionnal caveat! Report for errors or improvements are indeed welcome.

The script base-upload.sh (download it) takes a base_name as an argument, and optionally images or src. It uploads a fresh base on your server, or a fresh copy of the images/base or src/base folders. It performs the following steps:

  • creates a fresh base.gw file from the base on your personal computer.
  • extracts a listing of the content of bases/images/base bases/src/base and bases/src/base/images in three ls-xxx.txt files.
  • creates a remote.sh file (see remote-base.sh or remote-files.sh) depending on the second parameter.
  • creates a tar file containing base.gw, history, remote.sh and the three ls-*.txt files above.
  • sends the tar file to the remote server.
  • triggers on the remote server unfolding of the tar file and execution of the remote.sh script. Depending on the availability of /usr/bin/mail on your server, the result of this remote execution can be a mail containing the remote.log and three diff between images folders.

This procedure saves the previous folder of the base or its images and src folders with a "yyyy-mm-dd-hh:mm:ss" date tag. As time progresses, you may want to clean-up this accumulation of saves.

When uploading a base, the remote.sh shell script is executed on your remote server, and installs your base or its images at the proper location (according to the overall set-up described here).

If you launch the base-upload.sh script with the additionnal parameter images or src the script remote-files.sh is executed on your remote server, and installs the images or src/images folders for your base at the proper location (according to the overall set-up described here).

Depending on the size of your images folders, and on the number of new images requiring upload, you may prefer to upload images individually with your preferred ftp client rather than doing the bulk upload proposed here. Remember that the base upload script reports a form of comparison between the images folders on your personal computer and your server.

Debugging your remote server

Debugging your remote server may be tricky, but some systematic approach and several tools will help.

  • Verify first that your HTTP server works properly. This is achieved by typing your_server_name in the URL window of your browser which should return the content of index.html.
  • Verify that the cgi mechanism works. This is achieved by typing your_server_name/cgi-bin/test-cgi.sh as seen above (see #Folders and files).
If your server returns a "Internal server error", several hypothesis should be examined:
  • Your script test-cgi.sh does not work properly. Run it directly on a terminal window by typing ./test-cgi.sh (see #Folders and files).
  • Your server accepts only files with extension .cgi. Rename test-cgi.sh into test-cgi.cgi and try again.
  • The first two lines returned by your test-cgi.sh script are not exactly as shown (the second one should be a blank line, Note also that "Content-type text/html\n\n" did not work in my tests).
  • You also may want to verify that your "End-of-Lines" are correct for your server environment. Remember that there are three different such EOL encoding for Windows, Mac, and Linux!!
  • Examine the HTTP server log file on your server by typing:
tail /var/log/apache2/access.log (location in OVH-VPS configuration)
your environment may store access logs somewhere else, but this is the most likely place. You may discover this place by typing find / -name access.log -print.
Examination of the log file may give you a hint as to the nature of your problem.
  • Another typical issue is that of ownership of the various files associated with GeneWeb. In the case described here, ownership is user and group ownership is ftpusers. Depending on the specific method you have used to install GeneWeb, this may vary. Some discussions on the Yahoo! group forum about GeneWeb mentions geneweb for group ownership!
  • You may also want to look at the gwd log file if your GeneWeb server works only partially (welcome page is ok, but other pages do not work properly). This log file is specified in the gwd launch command. In our example, it sits at $DIR/gwd.log where $DIR depends on the specific version of GeneWeb you are currently running (see details in #The cgi-bin folder section above).
  • You may end up in a situation where GeneWeb works only partially, in particular it may miss some css style sheet or JavaScript files. One way of debugging this kind of problem consists in exploring the HTML source file produced by GeneWeb (your browser offers this capability addressed to "developers"). Is such source files, you will find reference to css and JavaScript files whose source should appear in your browser if you click on the link. In case of bad configuration, you will obtain an error messages such as "File not found" or "You do not have permission"…
Remember that some of the files needed for proper display are fetched by the HTTP server rather than by GeneWeb.

Access rights and protections

In CGI mode, gwd runs behind a standard HTTP server, typically Apache. As such, the owner of the gwd process is the owner of the HTTP server. For instance, with Apache, this owner is defined in the http.conf file and its default value is set to user: _www and group: —www. When running within a hosting environment, such as 1&1, you typically do not have access to this parameter. You must therefore organise the protection level of the various folders involved with GeneWeb appropriately:

  • read access is usually allowed by default
  • for wizards, gwd needs write access to bases/cnt/actlog, bases/cnt/robot (if you have activated the -robot_xcl parameter)
  • and when modifications are performed, gwd needs write access to bases/basename.lck, bases/basename.gwd/notes_link and to bases/basename.gwd/patches

Creating those files, and doing a sudo chown _www filename seems to be sufficient.

Access problems are reported in the HTTP error log file, unfortunately not always available in the case of shared hosting services!!

Access to various files through your hosted HTTP server is also controlled by your hosting service and through .htaccess files spread across your folders. Managing a coherent set of .htaccess files is not trivial and error prone!! The examples below apply to Apache version 2.4 only (earlier versions have different directives!!).

Options +FollowSymLinks should allow following symbolic links

Require all denied prevents access to this folder to all users. Require all granted allows access to this folder to all users. 

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

should restrict access to this folder to users supplying a valid password as defined by the htfriends.auth file.

htpasswd /Users/Name/SomeFolder/htfriends.auth UserName will trigger the process to add a new user to the list.



GeneWeb Manual

Rembrandt Old Man Reading a Book.jpg

Use and manage genealogical databases

Technical annex

Retrieved from "https://geneweb.tuxfamily.org/w/index.php?title=CGI&oldid=3993"