TOC

  1. How to Install WebGUI
    1. Getting Started
      1. Assumptions
      2. Other
    2. Programs
      1. Base Programs
      2. P5 Modules
      3. Command Line to Install All Programs
    3. Configuration
      1. Apache
      2. WebGUI
      3. MySQL
      4. Server Start Scripts
    4. Start the Servers
    5. Security Fixes
      1. Disable the account username/login from showing on the profile page
    6. Notes

How to Install WebGUI

Getting Started

Assumptions

  • You are installing to /data/
  • You are using FreeBSD 5.4 or greater as your host system
  • You are installing WebGUI 7.0.7 or higher
  • You are installing, or already using, MySQL 5.0
  • You are installing, or already using, Apache 2.0
  • You already have Perl 5.8.8 or greater installed

Other

  • "webguiuser" is the example MySQL user
  • "changeme" is the example MySQL password
  • "example.com" will be used as the example domain
  • All instances of 'IP_ADDRESS' should be changed to your server's external IP address
  • Apache will be listening on 3 ports:
    • 80: will forward to 443 (https)
    • 443: https -- for secure browsing
    • 81: For Spectre as it does not work with https nor with http due to the redirect
      • This port should probably be firewalled so no one can access and/or have an Apache rule that only allows access to localhost.

Programs

Base Programs

WWW: 

apache20 *
mod_perl2
libapreq2 †

   * make WITH_PROXY_MODULES=YES install

   † If you get '/usr/bin/ld: cannot find -lexpat' when running 'make install' then do the following:

	ee /usr/ports/www/libapreq2/Makefile

	Look for "CONFIGURE_ARGS+= --with-apache2-apxs=${APXS}" and add the following to the end:

	--with-iconv=/usr/local/ --with-expat=/usr/local/

	Save file and run 'make install'

Databases: 

mysql50-server

Graphics: 

ImageMagick


P5 Modules

WWW: 

p5-libwww
p5-libapreq2
p5-HTML-Template
p5-HTML-Template-Expr
p5-POE-Component-Client-HTTP
p5-Apache-DBI *

   * make WITH_MODPERL2=yes install

Databases: 

p5-DBD-mysql
p5-Cache-Memcached

Archivers: 

p5-Archive-Tar
p5-Archive-Zip

Mail: 

p5-Net-SMTP-Server

Devel: 

p5-Tie-IxHash
p5-Time-HiRes
p5-Log-Log4perl
p5-Date-Manip
p5-Pod-Coverage
p5-Test-MockObject
p5-Test-Deep
p5-DateTime
p5-DateTime-Format-Strptime
p5-DateTime-Format-Mail
p5-POE
p5-POE-Component-IKC
p5-Data-Structure-Util
p5-BSD-Resource

TextProc: 

p5-XML-Simple
p5-HTML-TagFilter
p5-Pod-POM
p5-Text-Autoformat

Net: 

p5-SOAP-Lite
p5-ResourcePool-Resource-Net-LDAP

Graphics: 

p5-Image-Size
p5-Image-Info

Converters: 

p5-JSON

Finance: 

p5-Finance-Quote

"CPAN": 

CPAN *
Tie::CPHash
DateTime::Cron::Simple
HTML::Highlight
Template †
Parse::PlainConfig
XML::RSSLite
Net::Subnets
Color::Calc ‡

   * (Upgrade to allow the -f option)
   † (Answer 'y' to first 2 dependencies, 'n' to 3rd)
   ‡ (answer "yes" to dependencies)


Command Line to Install All Programs

READ ALL FOOTNOTES ABOVE BEFORE USING THIS!

Be sure to check for an 'OK' after each Perl CPAN Module is installed when using the CPAN command lines given below.

cd /usr/ports/www/apache20 && make WITH_PROXY_MODULES=YES install && cd ../mod_perl2 && make install && cd ../libapreq2 && make install

cd /usr/ports/databases/mysql50-server && make install

cd /usr/ports/graphics/ImageMagick && make install

cd /usr/ports/www/p5-libwww && make install && cd ../p5-libapreq2 && make install && cd ../p5-HTML-Template && make install && cd ../p5-HTML-Template-Expr && make install && cd ../p5-POE-Component-Client-HTTP && make install && cd ../p5-Apache-DBI && make WITH_MODPERL2=yes install

cd /usr/ports/databases/p5-DBD-mysql50 && make install && cd ../p5-Cache-Memcached && make install

cd /usr/ports/archivers/p5-Archive-Tar && make install && cd ../p5-Archive-Zip && make install

cd /usr/ports/mail/p5-Net-SMTP-Server && make install

cd /usr/ports/devel/p5-Tie-IxHash && make install && cd ../p5-Time-HiRes && make install && cd ../p5-Log-Log4perl && make install && cd ../p5-Date-Manip && make install && cd ../p5-Pod-Coverage && make install && cd ../p5-Test-MockObject && make install && cd ../p5-Test-Deep && make install && cd ../p5-DateTime && make install && cd ../p5-DateTime-Format-Strptime && make install && cd ../p5-DateTime-Format-Mail && make install && cd ../p5-POE && make install && cd ../p5-POE-Component-IKC && make install && cd ../p5-Data-Structure-Util && make install && cd ../p5-BSD-Resource && make install

cd /usr/ports/textproc/p5-XML-Simple && make install && cd ../p5-HTML-TagFilter && make install && cd ../p5-Pod-POM && make install && cd ../p5-Text-Autoformat && make install

cd /usr/ports/net/p5-SOAP-Lite && make install && cd ../p5-ResourcePool-Resource-Net-LDAP && make install

cd /usr/ports/graphics/p5-Image-Size && make install && cd ../p5-Image-Info && make install

cd /usr/ports/converters/p5-JSON && make install

cd /usr/ports/finance/p5-Finance-Quote && make install

cpan -i CPAN
cpan -i Tie::CPHash
cpan -i DateTime::Cron::Simple
cpan -i HTML::Highlight
cpan -fi Template
cpan -i Parse::PlainConfig
cpan -i XML::RSSLite
cpan -i Net::Subnets
cpan -i Color::Calc

Configuration

Apache

Comment out the following lines in /usr/local/etc/apache2/httpd.conf (if needed): 

<IfDefine SSL>
</IfDefine>

ErrorLog /var/log/httpd-error.log
CustomLog /var/log/httpd-access.log combined

Add a line similar to the following at the very bottom of /usr/local/etc/apache2/httpd.conf: 

Include /data/apache-includes/default.conf

Put the following in /data/apache-includes/default.conf and edit as needed (you may want to play around with the max/min, etc servers): 

#Some basic config
LoadModule perl_module libexec/apache2/mod_perl.so
LoadModule apreq_module libexec/apache2/mod_apreq2.so

StartServers         5
MinSpareServers      5
MaxSpareServers     10
MaxClients          40
MaxRequestsPerChild 1000

DirectoryIndex index.html index.html index.php index.pl

ServerSignature Off

#PERL stuff for WebGUI
PerlSetVar WebguiRoot /data/WebGUI
PerlCleanupHandler Apache2::SizeLimit
PerlRequire /data/WebGUI/sbin/preload.perl

AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript

     <Directory />
          AllowOverride None
          SetHandler perl-script
          Options +ExecCGI FollowSymLinks
          Order Deny,Allow
          Allow from all
     </Directory>

     Alias /extras /data/WebGUI/www/extras
     <Directory "/data/WebGUI/www/extras/">
          Header set Cache-Control "max-age=36000"
     </Directory>

#Default http port will be forwarded to https
Listen IP_ADDRESS:80
#For SSL
Listen IP_ADDRESS:443
#Only for Spectre should be firewalled or access denied to all but localhost
Listen IP_ADDRESS:81

#For PHP
AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps

#SSL Stuff
SSLRandomSeed startup builtin
SSLRandomSeed connect builtin
AddType application/x-x509-ca-cert .crt
AddType application/x-pkcs7-crl    .crl
SSLPassPhraseDialog  builtin
SSLSessionCache         dbm:/var/run/ssl_scache
SSLSessionCacheTimeout  300
SSLMutex  file:/var/run/ssl_mutex

#Other Includes
Include /data/apache-includes/example.com.conf

Put the following in /data/apache-includes/example.com.conf and edit as needed: 

# Redirect any traffic coming into port 80 to SSL
<VirtualHost *:80>

     ServerName example.com
     DocumentRoot /data/domains/dummy
     RewriteEngine on
     RewriteRule ^/(.*)$ https://example.com/$1 [R]

</VirtualHost>

# The main SSL web
<VirtualHost *:443>

     ServerName example.com
     DocumentRoot /data/domains/example.com/public
     ServerAdmin admin@example.com

     SetHandler perl-script
     PerlInitHandler WebGUI
     PerlSetVar WebguiConfig example.com.conf
     PerlOptions +SetupEnv

     SSLEngine on
     SSLProtocol all
     SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+SSLv2:+EXP:+eNULL
     SSLCertificateKeyFile /data/certs/example.com.key
     SSLCertificateFile /data/certs/example.com.crt
     SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0
     <FilesMatch "\.(cgi|shtml|phtml|php|php3?)$">
          SSLOptions +StdEnvVars
     </FilesMatch>

     Alias /wiki /data/domains/example.com/wiki

     CustomLog /data/domains/example.com/logs/httpd-access.log combined
     ErrorLog /data/domains/example.com/logs/httpd-error.log

</VirtualHost>

# For Spectre only                               
<VirtualHost *:81>

     ServerName example.com
     DocumentRoot /data/domains/example.com/public
     ServerAdmin admin@example.com

     SetHandler perl-script
     PerlInitHandler WebGUI
     PerlSetVar WebguiConfig example.com.conf
     PerlOptions +SetupEnv

     CustomLog /data/domains/example.com/logs/httpd-access.log combined
     ErrorLog /data/domains/example.com/logs/httpd-error.log

</VirtualHost>

Create the "dummy" dir used for VHost:80: 

mkdir -p /data/domains/dummy

WebGUI

Download the latest tar and untar to /data/

Spectre: 

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

Edit the IP to match your server's IP and set port to '81'

Logs: 

cd /data/WebGUI/etc && cp log.conf.original log.conf && ee log.conf

Edit "log4perl.appender.mainlog.filename" as needed

WebGUI Config: 

cd /data/WebGUI/etc && cp WebGUI.conf.original example.com.conf && ee example.com.conf

Edit as needed making sure to at least edit the following lines: 

"sitename" : [ "example.com", "www.example.com"],
"dsn" : "DBI:mysql:example_com;host=localhost",
"dbuser" : "webguiuser",
"dbpass" : "changeme",
"spectreSubnets" : [ "IP_ADDRESS/32" ],
"spectreIp" : "IP_ADDRESS",

If you need a directory outside the WebGUI "realm" enable the following line and edit as needed: 

# "passthruUrls" : ["/icons", "/documentation/pdf", "/my-custom-application", "/server-status", "/perl-status"],

MySQL

mysql -u root -p -e "create database example_com"
mysql -u root -p -e "grant all privileges on example_com.* to webguiuser@localhost identified by 'changeme'"
mysql -u root -p -e "flush privileges"
mysql -u root -p example_com < /data/WebGUI/docs/create.sql

Server Start Scripts

The following is needed so the various services will start in the right order. 

cd /usr/local/etc/rc.d
mv mysql-server.sh 000.mysql-server.sh
mv 000.apache2libs.sh 001.apache2libs.sh
mv apache2.sh 002.apache2.sh

Create the Spectre start script: 

ee 003.spectre.sh

Paste: 

#!/bin/sh

case "$1" in
        start)
                cd /data/WebGUI/sbin/ && perl spectre.pl --daemon
                ;;
        stop)
                cd /data/WebGUI/sbin/ && perl spectre.pl --shutdown
                ;;
        restart)
                cd /data/WebGUI/sbin/ && perl spectre.pl --shutdown && perl spectre.pl --daemon                
                ;;
        *)
                echo ""
                echo "Usage: `basename $0` { start | stop | restart }"

                echo ""
                exit 64
                ;;
esac

Make script executable 

chmod +xo 003.spectre.sh

Start the Servers

/usr/local/etc/rc.d/000.mysql-server.sh start
/usr/local/etc/rc.d/002.apache2.sh start
/usr/local/etc/rc.d/003.spectre.sh start

Check the various logs for errors.

Security Fixes

Disable the account username/login from showing on the profile page

Edit Profile.pm 

ee /data/WebGUI/lib/WebGUI/Operation/Profile.pm

Look for the following which is on line 275 (in 7.0.7): 

$vars->{displayTitle} = $i18n->get(347).' '.$u->username;

And change it to: 

$vars->{displayTitle};

In the same file go to line 279 (in 7.0.7) and change: 

.'. '.

To this: 

.' '.

Notes

  • If Apache PHP5 module is needed then the LoadModule line MUST come before the mod_apreq2 and mod_perl LoadModule lines
  • If you want to customize the default WebGUI Apache error messages they are in /data/WebGUI/lib/WebGUI/Session/ErrorHandler.pm
  • You will, in all likeliness, see "Segmentation fault (core dumped)" when starting Apache and see it on a regular basis in the Apache error logs. This is due to a problem with the ImageMagick Perl module. If you don't need any sort of images on your WebGUI site then you can skip the installation of ImageMagick which will fix this problem. Otherwise, other than it being quite the nuisance, it is nothing to worry about.