Username Password
Bookmark and Share


Installing WebGUI is the most difficult task you’ll ever have to do with WebGUI. This is not because WebGUI is difficult to install, but rather that it has a lot of prerequisites. You have three options for this process:

  • Easy: Host WebGUI with a professional hosting provider that will install it for you.

  • Medium: Install using the WebGUI Runtime Environment.

  • Difficult: Install WebGUI from source.

WebGUI Hosting Provider

The easiest way to install WebGUI is to have someone else install it! There are WebGUI hosting providers all over the world, and using their services is often the fastest and easiest way to get WebGUI installed. WebGUI’s creator, Plain Black Corporation, also provides hosting services for WebGUI. You can learn more about Plain Black's hosting services at

Installation Using the WRE

The WRE, or WebGUI Runtime Environment, is the easiest way to install WebGUI if you want to install WebGUI on your own hardware. In addition to being the easiest way to install WebGUI yourself, the WRE also provides a number of utilities and performance enhancements to make administering WebGUI easier.


Download the latest WRE from

Platform Specifics

Now you need to prepare your operating system for the WRE. The following sections provide instructions for common systems.

All *nix Operating Systems

If you have installed the MySQL package for your system you'll need to uninstall it, or at the very least disable it and remove /etc/my.cnf, as it will interfere with the MySQL that comes with the WRE. You can run a separate MySQL if you wish. Just put it on a different port and move the my.cnf into the data folder that came with your MySQL distribution, which is often either /var/lib/mysql or /usr/local/mysql/data.

If you have installed the Apache package for your system, you'll need to uninstall it, disable it, put it on a different port, or when prompted by the WRE, run modproxy on a port other than port 80.

You need to add a user to the operating system for the WRE to run under. We recommend a user named “webgui”. On most platforms you can run one of the following commands to add the user:


adduser -s /sbin/nologin webgui

useradd -s /sbin/nologin webgui


You can use an existing user on your server like “nobody” for this purpose, but it's less secure to do so since other services may be using it as well.


A default server install is all that is necessary to run the WRE on Red Hat Enterprise Linux, Ubuntu, Debian, and CentOS. No further action necessary.

Mac OS X Tiger (10.4)

You will need to install the X Code developer tools from Apple. You can download them from


From the Ports system you'll need to install the “bash” and “libiconv” packages. You'll also need to run the following command:


ln -s /usr/local/bin/bash /bin/bash


Microsoft® Windows®

If you have IIS running on port 80, you'll either need to disable it, or choose a port other than port 80 for mod_proxy during the WRE installation process.

The WRE installs on drive C:, so you'll need to have at least 400MB available to install the WRE, plus whatever space you need for sites. Note that it is possible after the install to put site data on an alternate drive.

You'll also need to download and install a couple of utilities. First, you'll need an archive extractor, like 7-Zip or WinZip, that can extract tarballs. You'll also need a good text editor (Notepad and Wordpad don't count). We recommend Notepad++.

All Platforms

You should always read the docs/install.txt file that comes with the WRE in case there are any version specific changes of which you should be aware.

Extracting The Tarball

Use your archiver to extract the WRE tarball. If you have GNU tar or equivalent, use the following command to extract it:


mkdir /data
cd /data
tar xvfz /path/to/wre-0.8.0-rhel4-ia32.tar.gz


Initial Configuration

To configure the WRE you need to use the WRE Console. Use the following command to start it:




It will output the following:


Please contact me at:



However, for initial configuration you need to add /setup to the end of that URL (http://localhost.localdomain:60834/setup). Note that you can also access the WRE Console from an IP address or hostname bound to the machine, though you may have to open port 60834 in the firewall.

You will then be lead through a series of screens with questions for you to answer. In most cases you can simply use the defaults. If you make a mistake, don't worry. You can always go backward in the process and change your answers, until you come to the last screen.

Specify your WRE operating system user.

Note: Although other browsersmay work, this process is designed for Firefox and Internet Explore compatibility.

If you're not on Windows®, you'll also have the option of setting up a development only environment. This automatically configures mod_perl with Apache2::Reload so that you don't need to restart Apache every time you make a change to one of your WebGUI plugins. In addition, it will set up a dev site for you to work from.


Now, you can specify the ports for mod_proxy and mod_perl. If you're already running a web server on port 80, then you'll want to change the mod_proxy port to something else, perhaps 8080. Otherwise, you can safely leave the defaults.



Next, specify information about how you'd like MySQL configured. If you already have MySQL configured on another server and you'd like to use that, then simply specify the IP or hostname of the other server, its port, and a username and password that have full administrative privileges, and the WRE will configure itself to use that server.


Finally, you need to tell the WRE what subnet Spectre will use to communicate with WebGUI. The WRE tries to guess this information and puts its guess in the box for you. However, if it guesses incorrectly, or you'll be running Spectre on a different machine, or you have multiple IP addresses bound to this machine, you'll need to specify those changes here.

Note that the WRE accepts these IP addresses using CIDR notation. Therefore, if you want WebGUI to be able to accept requests from all IP addresses in a range, like –, you can specify that like “”. Or, if you have multiple IP's, you can specify them with a comma separated list like “,”.


The WRE is now ready to apply all the configuration options you gave it. From this screen you can either go back and change your answers, or you can do an automated install which will automatically download and configure WebGUI. You can also do a manual install, which assumes that you have already downloaded WebGUI and extracted it into /data/WebGUI. In most cases you want to choose “Automated Install”.


Depending on what options you chose in the previous screens, you should see a screen similar to the following.



Note: If any errors occur during this process do not continue. Instead shut down the local MySQL server, delete /data/wre/var/mysqldata and /data/wre/etc/wre.conf, correct the problem, and then restart the initial configuration process.


Set Up Cron Jobs

The last step in the configuration process is to set up the cron jobs as shown on your configuration screen. You can usually do this by typing:


crontab -e


And then add the lines like this:


0 0 * * * /data/wre/sbin/

*/3 * * * * /data/wre/sbin/

0 2 * * * /data/wre/sbin/


WRE Install Complete

You have now completed the WRE and WebGUI installation, but before you can use WebGUI you need to add a site. That is, unless you chose the development only option during the configuration process. To add a site skip to the next chapter.


Source Install

Instead of using the WRE, you can do what is known as a source install. It needs to be said that this process is difficult and time consuming, even for experienced system administrators. With the exception of a strong desire to just “do-it-yourself”, you should always use the WRE instead of opting for this installation method.

That said, if you do decide to proceed, you'll need to manually install and configure all of WebGUI's pre-requisites. The instructions for doing so are contained in the remainder of this chapter. For most of the prerequisites we have not provided detailed build instructions, because you'll likely be using the package management system on your operating system to install these packages.



WebGUI requires Perl 5.8 or higher, which you can download from, or you can likely install from your operating system's package management system. Be careful, though, because a lot of operating systems still distribute old versions of Perl instead of Perl 5.8.


Graphics Magick

WebGUI requires Graphics Magick 1.1 or higher, which you can download from, or you may be able to install using your operating system's package management system.

Also be sure to install the Perl Magick plugin that comes with Graphics Magick, and install the following image processing libraries:

  • libpng -

  • libungif –

  • libjpeg -

  • freetype -

For WebGUI 7.4 and below you can also use Image Magick (instead of Graphics Magick), which is sometimes easier to come by in native packages.



WebGUI requires MySQL 5.0 or higher, which you can download from, or you can likely install from your operating system's package management system. Be careful, though, because some operating systems still distribute old versions of MySQL instead of MySQL 5.0.



WebGUI requires Apache 2.0 or higher with mod_perl installed. You can download Apache from and mod_perl from, or you can likely install both of them using your operating system's package management system. Be careful, because a lot of operating systems are still distributing Apache 1.3 instead of Apache 2.0.

You'll also need to install libapreq2, which WebGUI needs to better communicate with Apache. You can download this from, or install from your operating system's package manager.

If you want a secure web site you'll also want to download and install OpenSSL 0.9.7m or higher from, and you can certainly install this from your operating system's package manager.

Now, you'll need to edit your httpd.conf to include the following directives. These should be placed at the end of the module loading section of your config file.


LoadModule apreq_module modules/

LoadModule perl_module modules/

PerlSetVar WebguiRoot /data/WebGUI

PerlRequire /etc/

PerlCleanupHandler Apache2::SizeLimit

PerlRequire /data/WebGUI/sbin/preload.perl

Alias /extras /data/WebGUI/www/extras


Now create a file called /etc/ and enter the following contents into it:


use Apache2::SizeLimit;

$Apache2::SizeLimit::MAX_PROCESS_SIZE = 100000;

$Apache2::SizeLimit::MAX_UNSHARED_SIZE = 75000;

$Apache2::SizeLimit::CHECK_EVERY_N_REQUESTS = 5;




You'll need to install a Perl module to make the above file work. To do that, run the following commands:


perl -MCPAN -e shell
install Apache2::SizeLimit


Do not yet start or restart Apache, as you still have to install WebGUI and add a site before it will successfully restart.



You need to download the latest version of WebGUI from and extract it to /data/WebGUI. It is possible to install it in another location, but you'll then need to modify the sbin/preload.perl program that comes with WebGUI, and the instructions given here to match your desired location. You should also read the chapter about the /data partition before making this decision.

To do this, run the following commands:


mkdir /data
cd /data
tar xvfz /path/to/webgui-7.4.8-stable.tar.gz


Now you need to configure the basic WebGUI system settings. To do this, run the following commands:


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


If you would like your logs to go to a specific place, then edit the path in log.conf. Other than that, you can leave the default settings, or read the chapter on logging later in this book to make additional modifications.

If you'll be running more than one site on this machine, then you'll want to edit spectre.conf to have a maxWorkers of 5, and a timeBetweenRunningWorkflows of 1. Other than that, you can leave the default settings, or read the chapter on Spectre later in this book to make additional modifications.

 Perl Modules

Finally, you'll need to install all of the Perl modules that WebGUI requires. To get a complete list of the Perl modules you'll need, you'll need to run the following commands:


cd /data/WebGUI/sbin
perl –simplereport


Once you know which Perl modules you need to install, you can install them using the following commands:


perl -MCPAN -e shell
install DBI


Replace “DBI” with the name of the module you wish to install, like “DBD::mysql” or “Net::SMTP”. There are more than 50 modules that you'll need to install in this way, and some of those have several prerequisite modules that will need to be installed as well. The CPAN system generally makes this easier by automatically downloading and installing prerequisites. However, depending upon your system, this process may or may not go smoothly. This is another reason to use the WRE.


Source Install Complete

You've now completed the source based installation, but your work is not done. You still have to add a site. See the next chapter on how to do that.

Keywords: apache install mysql perl source wre

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