Prerequisites

This is a guide to installing WebGUI (tested with v.7.7.20) from source as a user on Debian Lenny but it should work fine on other UNIX-like operating systems with a few modifications.

For the purposes of this article, the domain "example.net", the username "webgui" and the directory "~/local" for software and perl modules installed by the user will be used. A root prompt is represented by "example:~#" and a user prompt is represented by "example:~$" where "example" is the hostname and "~" is the current working directory.

The following are the requirements that are assumed to have been met.

Base packages that are required:

• build-essential
• apache2 (Specifically, apache2-mpm-prefork)
• libapache2-mod-perl2
• libapache2-request-perl (It might be possible to drop this requirement down to libapache2-mod-apreq2 and install Apache2::Request as a user)

The following additional packages are also required but can possibly be compiled as a user. How to do that is outside the scope of this article.

• libssl-dev
• libexpat1-dev
• libmysqlclient15-dev
• perlmagick
• unzip

The following are optional packages that maybe hosted on a different machine:

• mysql-server

They can all be installed as root with the following command:

example:~# aptitude install build-essential mysql-server apache2 apache2-mpm-prefork+M libapache2-mod-perl2 libapache2-request-perl libssl-dev libexpat1-dev libmysqlclient15-dev perlmagick unzip

Required Apache modules can be enabled with the following commands:

example:~# a2enmod perl

example:~# a2enmod apreq

example:~# a2enmod userdir

example:~# invoke-rc.d apache2 restart

Unpacking the Source

Download the source to your home directory and extract it.

example:~$ tar xzv --strip-components 1 -f webgui-7.7.20-stable.tar.gz

Creating the MySQL Database and User

You can use your host's database facilities to accomplish the equivalent of the following commands:

example:~$ mysql -u root -p -e "CREATE DATABASE WebGUI"

example:~$ mysql -u root -p -e "GRANT ALL ON WebGUI.* TO 'webgui'@'localhost' IDENTIFIED BY 'password'"

example:~$ mysql -u webgui -p WebGUI < docs/create.sql

Preparing the User Environment

The first thing that needs to be done is to prepare the user environment for Perl and CPAN. The PERL5LIB variable needs to be set for Perl (~/local/lib/perl/5.10.0:~/local/share/perl/5.10.0:~/local/lib/perl5:~/local/lib/perl/5.10:~/local/share/perl/5.10 for Debian) to use the modules that will be installed. Aside from this, ~/bin should be symlinked to ~/local/bin and should be added to the PATH (which is automatically done on Debian if it exists.) This can be accomplished by executing the following:

example:~$ echo "export PERL5LIB=~/local/lib/perl/5.10.0:~/local/share/perl/5.10.0:~/local/lib/perl5:~/local/lib/perl/5.10:~/local/share/perl/5.10" >> ~/.profile

example:~$ export PERL5LIB=~/local/lib/perl/5.10.0:~/local/share/perl/5.10.0:~/local/lib/perl5:~/local/lib/perl/5.10:~/local/share/perl/5.10

example:~$ ln -s local/bin

example:~$ ln -s www public_html

example:~$ mkdir -p var/log var/run

example:~/www$ chmod -R o+w *

Running CPAN

CPAN will ask for configuration to be done the first time it is run. The install directory should be set to $HOME/local via the PREFIX variable with Makefile.PL and the --install_base parameter for ./Build. See MyConfig.pm for a reference to the required settings. The following commands will reload the index, upgrade CPAN and upgrade all modules. You will most likely never be able to successfully upgrade all modules. Just upgrade everything that you can.

example:~$ perl -MCPAN -e 'CPAN::Shell->reload("index")'

example:~$ perl -MCPAN -e 'CPAN::Shell->upgrade("CPAN")'

example:~$ perl -MCPAN -e 'CPAN::Shell->upgrade(CPAN::Shell->r)'

Installing Required Modules

example:~/sbin$ ./testEnvironment.pl | grep '^Checking' | grep -v 'OK' | sed 's/^Checking for module \(.*\):\s\+.*$/\1/' | perl -MCPAN -ne 'chomp; CPAN::Shell->install($_);'

example:~$ perl -MCPAN -e 'CPAN::Shell->install("Template")'

Configuring WebGUI

All sample configuration files should be copied so that they can be used.

example:~/etc$ for i in $(ls); do cp $i $(echo $i | sed 's/\.original$//'); done

Modifying log.conf

The "log4perl.appender.mainlog.filename" configuration variable should be set to "/home/webgui/var/log/webgui.log"

Modifying spectre.conf

The "pidFile" configuration variable should be set to "/home/webgui/var/run/spectre.pid"

Modifiying WebGUI.conf

The "sitename" configuration variable should contain a list of URLs for your domain. In this case, it will contain "example.net" and "www.example.net". Since we are making WebGUI accessible in the user's public_html, the "gateway" variable should be set to "/~webgui/". Please note the trailing slash. The extras and uploads configuration variables should also be modified accordingly.

"sitename" : [
"example.net",
"www.example.net"
],
"gateway" : "/~webgui/",
"extrasURL" : "/~webgui/extras",
"extrasPath" : "/home/webgui/www/extras",
"uploadsURL" : "/~webgui/uploads",
"uploadsPath" : "/home/webgui/www/uploads",

Don't forget to also configure the database connection:

"dsn" : "DBI:mysql:database=WebGUI;host=localhost",
"dbuser" : "webgui",
"dbpass" : "password",

Adding Perl Module Paths to WebGUI Environment

The "~/sbin/preload.custom" file should contain the same paths that are specified for the PERL5LIB enviroment variable. On Debian, these are the following:

/home/webgui/local/lib/perl/5.10.0
/home/webgui/local/share/perl/5.10.0
/home/webgui/local/lib/perl5/i486-linux-gnu-thread-multi
/home/webgui/local/lib/perl5
/home/webgui/local/lib/perl/5.10
/home/webgui/local/share/perl/5.10

Testing WebGUI

example:~/sbin$ perl preload.perl

If you do not see any errors, that means WebGUI should run fine. If it complains about missing modules, install them.

Configuring mod_perl

If all went well with testing preload.perl, you can now install a .htaccess file in ~/public_html. It should contain the following:

PerlSetVar WebguiRoot /home/webgui
PerlCleanupHandler Apache2::SizeLimit
PerlRequire /home/webgui/sbin/preload.perl

SetHandler perl-script
PerlInitHandler WebGUI
PerlSetVar WebguiConfig ../home/webgui/etc/WebGUI.conf

Note the leading "../" when setting the WebguiConfig variable. It is required because WebGUI expects the path to the configuration file to be relative to /etc.

Testing Spectre

Run the following in one terminal to start Spectre:

example:~/sbin$ ./spectre.pl --run --debug

In another terminal, run the following to check if Spectre is alive and if WebGUI and Spectre can communicate with each other:

example:~/sbin$ ./spectre.pl --ping

example:~/sbin$ ./spectre.pl --test

Congratulations!

If all went well, WebGUI should now be accessible through http://example.net/~webgui/.  You can start configuring it as you normally do.

Additional things to do

You will probably want to write a script that checks if Spectre is alive, and if it is not, to start it. A crontab entry would be a good way to do that.

Acknowledgements

This would not have been possible without the support of the following:

• Plain Black for graciously providing WebGUI to the public as Free Software.
• The helpful people of irc://irc.freenode.net/#webgui who have patiently answered all my questions.