Username Password
Bookmark and Share

Source Install

Installing WebGUI from source is not a simple matter. If you have no experience installing open-source software you should either use the WebGUI Runtime Environment, seek professional assistance, or be prepared to run up against several hurdles. An experienced WebGUI installer can install WebGUI and all related components in about an hour. An experienced system administrator can expect to do it all in less than a day. Someone with no experience can expect to spend several days or even weeks reading and learning to install all of the required components of WebGUI. If you need help, please feel free to contact Plain Black.

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


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


MySQL ( 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 ( 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 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 and mod_perl can be obtained from 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 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 ( 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.



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/ 
LoadModule perl_module modules/
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. 


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

Setting Up A Site

Virtual Hosts

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

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>
        DocumentRoot /data/domains/        
        SetHandler perl-script
        PerlInitHandler WebGUI
        PerlSetVar webguiConfig # Under WebGUIRoot/etc
        Alias /extras /data/WebGUI/www/extras


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/
cd /data/domains/
mkdir logs
cp /data/WebGUI/etc/WebGUI.conf.original /data/WebGUI/etc/
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  (in /data/WebGUI/etc/) to match the database settings. It should look something like this:

"sitename" : ["","],
"dsn" : "DBI:mysql:www_example_com",
"dbuser" : "webgui",
"dbpass" : "password",
 "uploadsPath" : "/data/domains/",
"spectreSubnets" : ["", ""],


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 --shutdown
perl --daemon

Basic Configuration

Now that you've got WebGUI up and running, you can visit and get walked through setting up your WebGUI site.

Notes for FreeBSD

These notes are specifically for FreeBSD 7.0-RELEASE and may not apply to your case, but may help you if run into similar problems. The installation with the testEnvrinment script will probably fail with POE::API::Peek and Image::Magick (aka PerlMagick).

Image::Magick on FBSD

It is very plausible that Image::Magick will refuse to install via the CPAN shell. You will need to install with the port: /usr/ports/graphics/ImageMagick and make sure that su select PERL SUPPORT in the configuration dialog. This will install ImageMagick and the PerlMagick xs Perl libraries. Although the installation will finish with many warnings it will probably not work because your jpeg lib will be newer than the one require by libtiff. Try the command:

      perl -MImage::Magick -e'print $Image::Magick::VERSION'

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

      cd /usr/local/lib

      ln -s ln -s



It is plausible that this will also fail in FBSD at least in the versions mentioned above. That is: FBSD 7.0-RELEASE with system Perl 5.8.9. and POE-API-Peek-1.34

What was found was that some event tests were actually returning a different value than expected but after debugging were found to be the actual expected values, so it can almost be safely assumed that the tests have a slight glitch. You can force install with the CPAN shell or comment out these 3 specific tests in t/03-event.t :

    if($ver >= '0.31') {

        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];
        #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 {

Apache Configuration

In FBSD you will need to modifiy /usr/local/etc/apache22/http.conf and add at the end of the file:

PerlSetVar WebguiRoot /WebGUI
PerlCleanupHandler Apache2::SizeLimit
PerlRequire /usr/local/www/WebGUI/sbin/preload.perl

This is assuming that you installed WebGUI in the standard Apache directory in FBSD which is /usr/local/www/

You will also need to modify the file /usr/local/www/WebGUI/sbin/preload.perl and change this:

#my $webguiRoot = '/data/WebGUI';
my $webguiRoot = '/usr/local/www/WebGUI';


Keywords: Installation source

Search | Most Popular | Recent Changes | Wiki Home
© 2023 Plain Black Corporation | All Rights Reserved