WebGUI for Debian
=================

GETTING STARTED
---------------

These are the final steps to get WebGUI up and running in Debian.

1. Single Database setup.

If you want to have the database in the same machine, just install
mysql-server and create your database as follows so the configuration
files will work right away:

$ mysql -e "create database webguidb"
$ mysql -e "grant all privileges on webguidb.* to webgui@localhost identified by 'webgui'"
$ zcat /usr/share/doc/webgui/docs/create.sql.gz | mysql -uwebgui -pwebgui webguidb

If you want to have the database on a different machine, use different
names for your database and user, or a different password (please, do!),
just change the appropriate stanza in /etc/webgui/webgui.conf to match
your needs.

2. Multiple Database Setup

A single WebGUI installation can handle several virtual hosts as long
as you create a database and configuration file for each one. Just
copy /etc/webgui/webgui.conf to another name (say, /etc/webgui/mysite.conf),
create another database as explained before, and change the needed
stanzas in /etc/webgui/mysite.conf.

You'll probably need to change the Apache virtual host too, and
stop and start Apache in order to reload your configuration.

3. Check your configuration files in /etc/webgui

Any file ending in .conf inside /etc/webgui will be treated as a WebGUI
configuration, except for log.conf and spectre.conf. Therefore, do not
rename apache.config to apache.conf, nor add .conf files that are not
WebGUI config files; if you do, WebGUI will fail to start choking on
the "invalid config file".

4. Test your configuration before continuing.

You can test your WebGUI configuration at any time

# wg-testEnvironment

It will tell you if everything is ok. It will try to connect to
WebGUI's source site to find out the latest version available and
compare it with the installed one; you can safely ignore the warning
regarding availability of a newer version or, obviously, not being
able to access the site if you don't have Internet access at the time.

5. Apache configuration.

A sample configuration file is provided in /etc/webgui/apache.config.
Either copy or symlink it into Apache's configuration directory like

# ln -s /etc/webgui/apache.config /etc/apache2/conf.d/webgui

Once the file is in place you must enable Apache's perl and apreq modules

# a2enmod apreq
# a2enmod perl

and then either start or force-reload Apache2 using /etc/init.d/apache2

Once you start Apache you should get a message like 

Starting web server...
Starting WebGUI 7.10.24
        Loading webgui.conf
WebGUI Started!

The sample configuration assumes that WebGUI is accessed as /webgui so
any other application or static website will not be affected.

However, high performance installations usually require that WebGUI is
the only application being served, so you will need to change the default
configuration to fit your needs in that case. You can find suitable 
configuration files under /usr/share/doc/webgui/examples to have WebGUI
as the only application being served by Apache. This "standalone"
configuration defines a single Apache VirtualHost having its root handled
by WebGUI.

6. Start WebGUI's Spectre daemon

Once WebGUI's database is configured and Apache is starting up properly,
you must enable WebGUI's Spectre daemon. Failure to do so will prevent
any changes on the website, since the publishing workflow system will
not be available.

Edit /etc/default/webgui to enable startup, and use /etc/init.d/webgui
to start and stop the daemon.

Once started, you can use

# spectre --ping

and/or

# spectre --status

to check whether the daemon is available and what it's doing.

7. Using it for the first time.

Open your browser to http://localhost/webgui (if on the same machine) or the
appropriate URL from a remote one, in order to access WebGUI's initial
configuration sequence.

  * Admin Account

  You will be asked to set WebGUI's Administrator Account and set
  a password for it. Default values will be shown, but feel free to
  change them specially the password. You will also be able to set
  the default timezone and default language for the site.

  * Company Information

  You will be asked to set some details about your organization:
  name, mail contact address and URL. These are used to set up the
  home page and you can change them later if needed through the
  administrative interface so don't worry about setting them "perfect"
  the first time through.

  * Send WebGUI Statistics
 
  You will be asked whether or not to participate in the WebGUI
  Community Statistics Program. WebGUI can send usage statistics to
  a central statistics repository at webgui.org, helping developers
  understand the way WebGUI is used. If you click 'Enable', only
  anonymous statistical information will be sent to the repository.

  * Choose a Design

  You will have a chance to select the starting style for your
  site from a list with thumbnails. All styles are installed by
  default, so you'll be able to change them later if needed.

  * Page Builder

  You will be asked whether or not to use WebGUI Page Builder.

  If you click 'No, thanks' WebGUI will setup your site with the
  design you selected in the previous step using the standard pages
  WebGUI comes with. 

  If you click 'Yes, please!' you will be able to select some
  basic pages to be created and included by default in the site
  (Contact Us, Calendar, WiKi, Search, About Us, News) and even
  provide initial content for them. You can even list as many
  Forums as you want created and they will!

  Either way, you will be taken to the Homepage, where you can
  login to start customizing your site, adding users and content...

8. But it did not start!

If it does not start, check Apache's /var/log/apache2/error.log and
webgui's /var/log/webgui/webgui.log for hints on what could be wrong. 

UTILITY SCRIPTS
---------------

WebGUI comes with several utility Perl scripts intended to ease some
of the maintenance work, which are usually located in a private sbin
directory inside of WebGUI's file hierarchy. In order to comply with
Debian's Policy, this package places the scripts /usr/bin and
renames them from their standard names in order to drop the .pl extension
and have wg_ as prefix. Thus, the scripts are:

wg-changeIobStatus
wg-diskUsage
wg-fileImport
wg-findBrokenAssets
wg-fixWgaccess
wg-galleryImport
wg-generateContent
wg-installClass
wg-maintenanceMode
wg-purgeWGAccess
wg-rebuildLineage
wg-search
wg-syncToCdn
wg-testCodebase
wg-testEnvironment
wg-thumbnailer
wg-upgrade
wg-userImport

Check out each script manual page in order to find out what it does.

UPGRADES
--------

WebGUI comes with several scripts that help upgrade from one version
to another. The current Debian package attempts the automatic upgrade
using those scripts and they work out of the box in most cases. Note
that every upgrade step takes a backup of WebGUI's database and places
it in /var/backups. If the automatic upgrade succeeds, you can
remove those backups.

If the automatic upgrade fails, you may want to perform the upgrade
manually using the scripts provided in /usr/share/webgui/upgrades.

Begin the upgrade by shutting down Spectre either by using the startup
scripts

# /etc/init.d/webgui stop

or manually via

# spectre --stop

Then, execute the main upgrade script

# wg-upgrade --help

and follow the instructions. Once the script has finished, restart Spectre
either by using the startup script

# /etc/init.d/webgui start

or manually via

# spectre --start

Finally, restart Apache for the changes to take effect.

You should be able to upgrade any WebGUI installation from 7.8.13 on.

MAINTENANCE MODE
----------------

The utility script

wg-maintenanceMode

toggles an internal WebGUI flag signaling whether or not the system
is available for normal use or if it is under maintenance. This can
be used during upgrades or during planned outages, so you don't need
to stop the application completely and your users won't get 404
errors on account of Apache not being available.

You can have a custom static HTML page served while the system is under
maintenance. The current WebGUI version has the static page location
hardcoded, and the Debian package puts it in

/etc/webgui/maintenance.html

Remember that this is a static page, so if you need to use CSS or
images provided by WebGUI, they must be available as static objects,
tipically via /extras or /uploads. A simple trick is to create a
page in WebGUI and then export it.

ENABLING SPELL CHECKING
-----------------------

WebGUI uses TinyMCE as the rich text editor for content managers and
also for writing in forums. If you want to add server-side spell checking
facilities for one or more languages:

1. Install aspell and needed languages. For instance, to have english
and spanish server-side spell checking you would need

aptitude install aspell aspell-en aspell-es

2. Change WebGUI' s configuration file to include the available
dictionaries and mark one of them as default. In this example

  "availableDictionaries" : [
    {
      "id"      : "en_US",
      "name"    : "English",
      "default" : "1"
    },
    {
      "id"      : "es",
      "name"    : "Castellano"
    }
  ],

The "id" field must have any of the valid aspell dictionary names,
as shown by

$ aspell dicts

whereas the "name" field can have any suitable description intended
for the user, since it will show verbatim in the Spell Checking menu.

3. You must add the Spell Checker button in the TinyMCE Templates.
Working as a WebGUI Administrator, use the Admin Console and go to
the Asset Manager. Navigate through the Asset Browser following the
path

   Root -> Import -> RichEdit

There you'll find the Templates for the Content Manager's Rich Edit
and the Forum Rich Edit. Following the Edit link for each one you'll
be able to enable the "Server Side Spell Checker" button, by adding it
to any of the three rows of TinyMCE's toolbar.

4. The next time you use either Rich Editor, you should have a
Spell Check button. If you've defined more than one available dictionary,
you'll see a drop down menu listing them.

DATABASE CONNECTION POOLING
---------------------------

WebGUI can take advantage of Apache::DBI to reuse and multiplex
connections to MySQL, improving performance in single-database
scenarios. You have to install Apache::DBI

   aptitude install libapache-dbi-perl

and then edit /usr/share/webgui/sbin/preload.perl, uncomment

use Apache::DBI ();

and then restart Apache.

Connection pooling is NOT recommended if you have multiple websites
under a single WebGUI installation through virtual hosts, or a 
replicated database backend.

EXTENDING WEBGUI
----------------

If you intend to write extensions for WebGUI as Macros or Assets, you
should place the additional Perl modules in /usr/share/local/webgui/lib
mimicking the structure of /usr/share/webgui/lib. Apache will load
any modules under this directory on startup and reload, so after
adding your Perl modules there, you should restart Apache to make
WebGUI use them. If you want to have several directories holding
custom Perl modules for WebGUI, add them to /etc/webgui/preload.custom.

Note that you *must* create the needed directories before installing
your custom modules. For instance, if you write your own Foo.pm for
a WebGUI Macro named 'foo', you should

# mkdir -p /usr/local/share/webgui/lib/WebGUI/Macro
# cp Foo.pm /usr/local/share/webgui/lib/WebGUI/Macro
# chmod 644 /usr/local/share/webgui/lib/WebGUI/Macro.pm
# /etc/init.d/apache2 restart

If you write your own Frobnicator.pm for a WebGUI Asset named Frobnicator,
you should

# mkdir -p /usr/local/share/webgui/lib/WebGUI/Asset
# cp Frobnicator.pm /usr/local/share/webgui/lib/WebGUI/Asset
# chmod 644 /usr/local/share/webgui/lib/WebGUI/Asset/Frobnicator.pm
# wg-installClass WebGUI::Asset::Frobnicator --config=webgui.conf
# /etc/init.d/apache2 restart

There's plenty of information in http://www.webgui.org for developers,
and you can find template modules in

/usr/share/webgui/lib/WebGUI/Macro/_macro.skeleton
/usr/share/webgui/lib/WebGUI/Asset/_NewAsset.skeleton

If you intend to submit patches or extensions to the core WebGUI, please
make sure your code adheres to WebGUI's coding standards. Just configure
perltidy so it uses WebGUI's preferred configuration, which can be copied
from /usr/share/doc/webgui/examples/.perltidyrc to your WebGUI's
development or personal directory.

TESTING WEBGUI's CODEBASE
-------------------------

You can test all of WebGUI's installed codebase using wg-testCodebase.
This is particularly useful if you develop additional Assets and Macros,
or change WebGUI's code in any way you see fit, and want to be sure
you haven't broken anything. To be able to use wg-testCodebase, you need
to install the Perl modules listed as Recommends and Suggests dependencies
for the package (libtest-* and libdevel-*).

Several tests are *destructive*, that's why testing is strongly recommended
on *testing* installations.

All tests assume WebGUI is setup to handle Apache's root location
and that users Visitor and Admin have a timezone of America/Chicago.

There are additional WWW::Mechanize based tests to navigate through
the live site. In order to run them you need to have a proper installation
of WebGUI with Apache listening on localhost, and set the environment
variable WEBGUI_LIVE=1 before running the test suite.

TRANSLATIONS
------------

WebGUI includes english, spanish, german and dutch translations out of
the box. There are additional translations you can download an install:

1. Go to http://i18n.webgui.org
2. Choose a language to get a .tar.gz created on the fly for
   download with the current translated messages.
3. Extract the files in /usr/share/webgui/lib/WebGUI/i18n

Note that except for the four default translations, most translations
are partial, but you are able to contribute to the translation online
before you download it.

TODO
----

- I'll be adding debconf/dbconfig support so database creation becomes
  easier.

- I'll be adding some documentation on WebGUI that I've gathered, once
  I sort out the good bits.

--
Ernesto Hernández-Novich <emhn@usb.ve> 
Tue, 17 Jan 2012 18:16:34 -0430
