| Plain Black login Visitor  |  download download  |  search search  |  print print |
| |
| |

Ruling WebGUI: TOC


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.

Perl Modules

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
install LWP
install DBI
install DBD::mysql
install Time::HiRes
install Archive::Tar
install Compress::Zlib
install IO::Zlib
install Digest::MD5
install HTML::Parser
install SOAP::Lite
install Cache::Cache


Download the most recent copy of WebGUI (www.plainblack.com/download).

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/
touch /data/webgui.log
chown nobody /data/webgui.log

Cron Jobs
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.

Apache Configuration
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 etc.

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.

<Directory />
  Options ExecCGI FollowSymLinks
<Files ~ "index\.pl$">
    SetHandler perl-script
    PerlHandler ModPerl::Registry
PerlRequire /data/WebGUI/sbin/preload.perl
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 instead.

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.

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

<VirtualHost *:80>
  DocumentRoot /data/domains/example.com/www/public
  ServerName www.example.com
  ServerAlias example.com
  ErrorDocument 404 /index.pl/page_not_found
  CustomLog /data/domains/example.com/www/logs/access_log combined

NOTE: 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 WebGUI.

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

mkdir -p /data/domains/example.com/www/public
cd /data/domains/example.com/www
mkdir logs
cp /data/WebGUI/etc/WebGUI.conf.original /data/WebGUI/etc/www.example.com.conf
cd public
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:

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

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

WebGUI Gateway
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);
use strict;
use WebGUI;

print WebGUI::page($webguiRoot,$configFile);

TIP: If you're using mod_perl 1.0 you'll need to edit /data/WebGUI/sbin/preload.perl to according. Read the instructions contained in the file for details.

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

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

NOTE: The default username is "Admin" and the default password is "123qwe".

Basic Configuration

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:

user: Admin
password: 123qwe

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.

| Designed By Plain BlackGet FirefoxPowered By WebGUI |