What You'll Need

You'll need several things to install WebGUI 7.5. The following is an overview of those items. We'll get more detailed as to what to do with them as we progress.

• A good text editor capable of saving Linux style line-endings.*
• A good decompressor for your operating system.
• A server running a supported operating system or a hosting provider that supports WebGUI.**
• Privileges on the server to install all the necessary software. Though it is sometimes possible to do this without root access, it's not likely that you'll be successful without root access.
• Perl 5.8.8 or higher.
• Apache 2.0.55 or higher.
• MySQL 5.0.15 or higher.
• Several Perl modules from the CPAN archive.
• A copy of WebGUI 7.5.0 or higher.

* NOTE: Linux line-endings have only a line-feed character marking the end of a line in a file. This is denoted as "\n" in most programming languages (binary value 0x0A in a hex viewer).

** NOTE: Many companies use WebGUI as the platform for their corporate intranet and/or website. These companies have dedicated servers in place to install and host WebGUI. However, if you don't have a server, there are a few options available. You can purchase a custom built one, or you can rent space on an Internet Hosting Provider (IHP). If you are interested in renting space, you should consider hosting your website with the experts at Plain Black. 

Linux Is Preferred

Our preferred operating system platform is Linux with a 2.4 or 2.6 kernel. You can download a great copy of Linux from Red Hat Software (fedora.redhat.com) for free. Another reason you may wish to download and install Red Hat's Fedora Core distribution of Linux is that it comes with precompiled versions of Apache, Image Magick, MySQL, Perl, mod_perl, and several of the Perl modules. This will speed up your install process, and save you a lot of headache.

Text Editor

You'll need to get a good text editor because you'll be editing a number of configuration files.

There are a number of great text editors on the market. Some free, some expensive. In our opinion the best text editor is called VIM and can be downloaded from www.vim.org for free. However, this is a highly complicated and powerful text editor that may confuse and intimidate some users so we've provided a list of some other text editors that may be used in VIM's stead.

• Codewrite (www.premia.com/products/codewright)
• Emacs (www.emacs.org)
• Joe (sourceforge.net/projects/joe-editor)

Decompressor

Most Linux and Unix environments come with utilities called gunzip and tar. Those will work just fine for our purposes.

MySQL

MySQL (www.mysql.com) is one the most popular RDBMS on the planet. In fact, its install base greatly outnumbers that of any other RDBMS on the market. It is popular for good reason; it is powerful, speedy, and free.

Though MySQL is available as source code that you can compile, unless you are familiar with compiling C++ applications, we recommend that you download the binary distribution for your operating system (www.mysql.com/downloads). MySQL can be downloaded as a pre-compiled binary for almost every operating system imaginable.

NOTE: Though not installed by default, the MySQL RPMs are on the Fedora CDs.

Perl 5.8

Perl is the programming language WebGUI is written in and that it relies upon. It is freely downloadable from www.perl.com. You must install Perl 5.8 or higher; any version earlier than that is too outdated and does not include the methods required to make WebGUI run. 
  

Apache 2.0

Apache is our web server of choice. It is standards compliant, robust, secure, and runs on almost every operating system.  mod_perl keeps the Perl interpreter and a pre-compiled copy of WebGUI in memory for increased performance.

You can download Apache and also get its documentation from httpd.apache.org and mod_perl can be obtained from perl.apache.org. After obtaining both the Apache web server and mod_perl, follow the following instructions to install and configure the two. 

 Apache 2.0 is the only version of Apache to use with WebGUI 7.5.0 and higher. It is more feature rich and much faster than 1.3 on many platforms. The following instructions will install Apache 2.0 and mod_perl 2.0.

tar xvfz httpd-2.0.x.tar.gz
cd httpd-2.0.x
./configure --prefix=/data/apache --enable-rewrite=shared
make
make install
cd ..
tar xvfz mod_perl-2.0-current.tar.gz
cd mod_perl-2.0_x
perl Makefile.PL MP_APXS=/data/apache/bin/apxs
make && make test
make install

Image Magick

Image Magick (www.imagemagick.org) is an image manipulation program for Linux. It is used in WebGUI for automatic generation of thumbnails of images uploaded to WebGUI. You can optionally run WebGUI without installing Image Magick, but then none of the thumbnail or image resizing functions in WebGUI will work.

There are two parts to the Image Magick install, and two ways to install it. The two parts are the C libraries and the Perl libraries (sometimes known as Perl Magick or also Image::Magick). The two install types are precompiled packages, and install from source. We'll show you both.

Also note that Image Magick is capable of being extended with many other packages for additional functionality. Some of those packages are freetype, libjpeg6b, libungif, libtiff, libxml2, and libpng. Whether those libraries come with your distribution or not is dependent upon the distribution. They all come with Fedora Core.

 

WebGUI

Download the most recent copy of WebGUI.

 

Centralized Files

Install WebGUI to a central location that all your sites can use. We'll use /data/WebGUI for our example. Run the following commands:

tar -zxvf webgui-x.x.x.tar.gz
mv WebGUI /data/
cd /data/WebGUI/etc
cp log.conf.original log.conf
touch /var/log/webgui.log
chown nobody /var/log/webgui.log

 

 Apache Configuration

The following changes will set the server-wide directives necessary to host multiple WebGUI sites under one installation of Apache. Edit your Apache installation's httpd.conf.

Make sure the following directives are included in this order near the top of the config file. 

LoadModule apreq_module modules/mod_apreq2.so 
LoadModule perl_module modules/mod_perl.so
PerlSetVar WebguiRoot /data/WebGUI         # This must in the main server section NOT in a <VirtualHost *:80> block 
PerlCleanupHandler Apache2::SizeLimit
PerlRequire /data/WebGUI/sbin/preload.perl

 

TIP: If you are installing into a directory other than /data then you'll need to modify preload.perl accordingly. 

Spectre

You need to set up WebGUI's background processor (called Spectre) to start when your server starts. There are lots of ways to do this and they are different on every operating system. Therefore we can't provide any instructions for to do this, other than the most general instructions.

First copy the spectre config file and modify it to your own needs:

cd /data/WebGUI/etc
cp spectre.conf.original spectre.conf

Then you can start Spectre:

cd /data/WebGUI/sbin
perl spectre.pl --daemon

Perl Modules

WebGUI requires several CPAN modules. You don't need to download them in advance because WebGUI can install them for you when you run the following commands.

cd /data/WebGUI/sbin
perl testEnvironment.pl

Setting Up A Site

Virtual Hosts

Add a virtual host to your Apache configuration directly after NameVirtualHost *:80:

NOTE: From here until the end of the chapter anything marked in italic references something that will be specific to each site you install. This means that you should not use what is typed there, but instead replace it with your particular install.

<VirtualHost *:80>
        ServerName www.example.com
        ServerAlias example.com
        DocumentRoot /data/domains/www.example.com/public        
        SetHandler perl-script
        PerlInitHandler WebGUI
        PerlSetVar webguiConfig www.example.com.conf # Under WebGUIRoot/etc
        Alias /extras /data/WebGUI/www/extras
</VirtualHost>

TIP: You need to have PerlOptions +SetupEnv in the <VirtualHost> block if you've turned it off elsewhere. By default it's already on. The environment variables it creates are required for WebGUI to function, so if you've turned it off, you need to re-enable it.

 WebGUI Files

Now we need to set up the WebGUI file system. Simply enter the following commands:

mkdir -p /data/domains/www.example.com/public
cd /data/domains/www.example.com
mkdir logs
cp /data/WebGUI/etc/WebGUI.conf.original /data/WebGUI/etc/www.example.com.conf
cd public
mkdir extras
cp -R /data/WebGUI/www/uploads .
 chown -Rf nobody uploads

Note: In the last command, replace "nobody" with your http system user, if it is different.

WebGUI Database Configuration

Now we need to set up the WebGUI database and configure WebGUI to use it. Then type the following commands:

cd /data/WebGUI/etc
mysql -e "create database www_example_com"
mysql -e "grant all privileges on www_example_com.* to webgui@localhost identified by 'password'"
mysql -e "flush privileges"
mysql -uwebgui -ppassword www_example_com < /data/WebGUI/docs/create.sql

 

WebGUI Site Configuration

 

 Now edit www.example.com.conf  (in /data/WebGUI/etc/) to match the database settings. It should look something like this:

"sitename" : ["www.example.com",example.com"],
"dsn" : "DBI:mysql:www_example_com",
"dbuser" : "webgui",
"dbpass" : "password",
 "uploadsPath" : "/data/domains/www.example.com/public/uploads",
"spectreSubnets" : ["127.0.0.1/32", "123.123.123.123/32"],

 

The Restart

After you have everything set up for the site, you need to restart Apache and Spectre so they can reload the configurations.

Restarting Apache works differently on different platforms. Generally it uses a program called apachectl, and therefore would work like this:

apachectl -k stop
apachectl -k start

To restart Spectre run the following commands:

cd /data/WebGUI/sbin
perl spectre.pl --shutdown
perl spectre.pl --daemon

Basic Configuration

Now that you've got WebGUI up and running, you can visit http://www.example.com and get walked through setting up your WebGUI site.

An see if you get any errors regarding libjpeg. If so, something like this may help you:

    if($ver >= '0.31') {
        $_[KERNEL]->yield('dummy');

        my @queue;
        eval { @queue = $api->event_queue_dump() };
        ok(!$@, "event_queue_dump() causes no exceptions: $@");

        #THIS LINE...
        #is(scalar @queue, 1, "event_queue_dump() returns the right number of items");

        my $item = $queue[0];

        #AND THESE THREE
        #is($item->{type}, 'User', 'event_queue_dump() item has proper type');
        #is($item->{event}, 'dummy', 'event_queue_dump() item has proper event name');
        #is($item->{source}, $item->{destination}, 'event_queue_dump() item has proper source and destination');
    } else {