Installing WebGUI is not a simple matter. If you have no experience installing open-source software you should either 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.
The following instructions are provided for a source-based installation of WebGUI. Source-based installs are the recommended installation method for production environments. There are also unsupported installation instructions available.
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 headaches.
WebGUI requires several CPAN (www.cpan.org) modules. You don't need to
download them in advance, the following steps will download, compile,
and install the modules you need.
perl -MCPAN -e shell
Download the most recent copy of WebGUI (www.plainblack.com/download
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/
chown nobody /data/webgui.log
You need to set up a cron job to run WebGUI's maintenance functions. It should be set to run every hour. Typically you'll type crontab -e
at the command line to edit a cron job. Enter a line that looks like this:
0 * * * * cd /data/WebGUI/sbin/; perl runHourly.pl >/dev/null 2>/dev/null
This cron job will now run WebGUI's maintenance functions every hour on the hour.
The following changes will set the server-wide directives necessary to
host multiple WebGUI sites under one installation of Apache.
First search for the directive that looks like DirectoryIndex
and add index.pl
to it so it will look similar to the following directive:
DirectoryIndex index.pl index.html
To enable mod_perl on all sites add the directives highlighted in bold blue
in and around the default <Directory />
directive. If you don't wish to enable mod_perl on all sites, you can add these statements to individual virtual hosts.
Options ExecCGI FollowSymLinks
<Files ~ "index\.pl$">
Alias /extras /data/WebGUI/www/extras
If you're using Apache 2.0 you need to have PerlOptions +SetupEnv
in the <Files>
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.
If you're using Apache 1.3 and mod_perl 1.0 then Modperl::Registry
needs to be Apache::Registry
If you want mod_perl to pick up all .pl
files then you should do
<Files ~ "\.(pl)$">
From here until the end of the chapter anything marked in bold blue
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.
Add a virtual host to your Apache configuration directly after NameVirtualHost *:80
ErrorDocument 404 /index.pl/page_not_found
CustomLog /data/domains/example.com/www/logs/access_log combined
You'll need to perform
the steps from Virtual Hosts, WebGUI Files, WebGUI Database
Configuration and WebGUI Gateway for each site you wish to run using
Now we need to set up the WebGUI file system. Simply enter the following commands:
mkdir -p /data/domains/example.com/www/public
cp /data/WebGUI/etc/WebGUI.conf.original /data/WebGUI/etc/www.example.com.conf
cp /data/WebGUI/www/index.pl ./
cp -R /data/WebGUI/www/uploads ./
chown nobody uploads
WebGUI Database Configuration
Now we need to set up the WebGUI database and configure WebGUI to use it. Then type the following commands:
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
Now edit www.example.com.conf
to match the database settings. It should look something like this:
sitename = www.example.com
dsn = DBI:mysql:www_example_com
dbuser = webgui
dbpass = password
logfile = /data/webgui.log
extras = /extras
uploadsURL = /uploads
uploadsPath = /data/domains/example.com/www/public/uploads
Now we need to set up the WebGUI gateway to use the config file you just created. Use the text editor of your choice to edit /data/domains/example.com/www/public/index.pl
our ($webguiRoot, $configFile);
$configFile = "www.example.com.conf";
$webguiRoot = "/data/WebGUI";
unshift (@INC, $webguiRoot."/lib");
use CGI::Carp qw(fatalsToBrowser);
If you're using mod_perl
1.0 you'll need to edit /data/WebGUI/sbin/preload.perl
Read the instructions contained in the file for details.
If you are installing into a directory other than /data then you'll need to modify preload.perl
Now you've got WebGUI installed. All you need to do is log in and build your site. Point your web browser to http://www.example.com
The default username is "Admin" and the default password is "123qwe".
Now that you've got WebGUI up and running, there are a few things
you'll want to configure. First, log in to WebGUI using the default
administrator account. The default account information is as follows:
You should change the password for the default admin account
immediately after logging in. If you leave the default account
information then anybody can log in to your site and destroy it.
After logging in, go to the account page and Turn admin on
. Select Manage settings.
from the admin menu.
Now choose Edit Company Information and fill it in with your settings.
Now you're ready to begin using WebGUI.