How to install Gorg

1.  Introduction

Gorg is a back-end XSLT processor for an XML-based web site. XML source files are transformed and served on-the-fly. Output files and their dependencies are cached. Its main features are:

• Works with apache, lighttpd or webrick (ruby's own web server)
• Uses efficient caching
• Generates consistent HTTP headers when several web nodes serve the same content
• Implements its own compression (aka mod_gzip), i.e. it does not rely on the web server to compress its output
• Supports client-side caching
• Your XSL can accept and write cookies
• Provides its own search engine (site indexing will be substantially updated in a later version)

Gorg allows you to serve your own local copy of http://www.gentoo.org. It can use either a cgi or a fastcgi script with apache or lighttpd, or even use its own stand-alone web server. Its name is short for Gentoo.org because it was created with Gentoo's site in mind when it was felt that a replacement for AxKit was required.

Gorg has been tested on x86, amd64, alpha, sparc, ppc, mips & hppa with the following packages:

>=net-www/apache-2.0.55
>=www-apache/mod_fcgid-1.0.8 

>=dev-lang/ruby-1.8.4
>=dev-libs/fcgi-2.4.0  
>=dev-ruby/ruby-fcgi-0.8.6
>=dev-libs/libxml2-2.6.23
>=dev-libs/libxslt-1.1.15
(In the unlikely case you want to fiddle with gorg's own search engine)
>=dev-db/mysql-4.0.26 (up to and including 5.*)
>=ddev-ruby/ruby-dbi-0.0.21
>=ddev-ruby/mysql-ruby

Download:

• Gorg's changelog
• Gorg's ebuild
• Gorg's tarball

2.  Installing Gorg

Adding gorg's overlay

If you haven't done so yet, install layman:

# emerge layman
# echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf

Then, add gorg's overlay as follows. If gorg is not available in the default list of overlays, just use gorg's own list.

# layman -a gorg

(If gorg is not in the default list:)
# layman -o http://gentoo.neysx.org/mystuff/gorg/overlay.xml -a gorg

Installing gorg

Define your USE flags to allow apache with or without mod_fcgi, or not depending on how you want to use it. The mysql USE flag is only required for the integrated search engine.

(With apache support)
# echo www-servers/gorg fastcgi apache -mysql >> /etc/portage/package.use

(Without apache support)
# echo www-servers/gorg -fastcgi -apache -mysql >> /etc/portage/package.use

(Check dependencies are available for your architecture)
# emerge -vp gorg

(Install gorg)
# emerge gorg

3.  Configuring Gorg

Configuring apache

You may skip this section if you are not going to use apache at all.

If you want to use fastcgi, which you should anyway, you'll need to add -D FCGID to the APACHE2_OPTS variable in /etc/conf.d/apache2.

Then, integrate the apache configuration directives from the provided sample file /etc/gorg/vhost.sample into your own vhost configs, e.g.: /etc/apache2/vhosts.d/10_gorg.conf. Comments in the sample config file will guide you.

Finally, copy or symlink the (c)cgi scripts from /usr/lib/ruby/site_ruby/1.8/gorg/fcgi-bin/gorg.fcgi and /usr/lib/ruby/site_ruby/1.8/gorg/cgi-bin/{gorg,search}.cgi into your web site (f)cgi directories and check they are executable. You should copy search.cgi only if you are going to use the integrated search engine.

Configuring Gorg

Create a copy of the sample config file /etc/gorg/gorg.conf.sample named /etc/gorg/gorg.conf and edit it. Comments will help you define your own parameters. You need to define at least your web document root directory.

If you do not want to use the default /etc/gorg/gorg.conf config file, you'll need to define an environment variable called GORG_CONF that points to the config file.

Getting the missing files

Assuming you'll serve your local copy of CVS, or a copy if, or symlinks to it, you need to download some files from the dyn directory.

# cd to your htdocs directory
$ cd /path/to/your/document/root
/htdocs $ cd dyn
/htdocs $ wget -O news-index.xml http://www.gentoo.org/dyn/news-index.xml?passthru=1
/htdocs $ cd ..
# If you ever need other data from the /dyn directory,
# I am sure you get the picture on how to do it.

You also need to make the pictures available to your browser. The images directory is one level above htdocs. Just define a symlink to it and you're set.

/htdocs $ ln -si ../images images
# It should look like this:
/htdocs $ $ ls -l
drwxr-xr-x   3 neysx users  128 Sep 14 17:45 css
drwxr-xr-x  31 neysx users  744 Oct 26 00:03 doc
drwxr-xr-x   3 neysx users  544 Nov  2 16:53 dtd
drwxr-xr-x   3 neysx users  168 Nov  3 16:24 dyn
-rw-r--r--   1 neysx users 1406 Jun  7  2003 favicon.ico
lrwxrwxrwx   1 neysx users   10 Oct 21 22:29 images -> ../images/
-rw-r--r--   1 neysx users  190 Nov  9  2002 index.xml
drwxr-xr-x  16 neysx users  384 Apr  1  2004 main
drwxr-xr-x  17 neysx users 6960 Nov  3 15:34 news
drwxr-xr-x   8 neysx users  192 Oct 23 14:52 proj
drwxr-xr-x   4 neysx users   96 Sep 17 14:05 security
drwxr-xr-x   3 neysx users  736 Nov  2 16:40 xsl

# Your local CVS probably shows a few more entries, but at least
# those mentioned above should be available and kept up-to-date.
# Also remember to keep your images directory current.

4.  Running Gorg

The stand-alone web server

The easiest way to try it out is to run gorg. It should display something like:

$ gorg


Starting the Gorg web server on port 8008

Hit Ctrl-C or type "kill 31479" to stop it

Point your browser to http://localhost:8008 and you should see your favourite site.

With apache

Restart apache (/etc/init.d/apache2 restart) and visit http://localhost assuming you're installing on your own workstation.

If you used static fastcgi servers, you should see them with a top -u apache.

If it doesn't work, try the stand-alone web server (type gorg). If this doesn't work either, check your /etc/gorg/gorg.conf config file. If it does work, please check your apache config files and your logs. If all fails, contact me.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.