Skip to content
Branch: master
Go to file
This branch is 437 commits ahead, 62 commits behind plainblack:master.


Failed to load latest commit information.
Latest commit message
Commit time

The WebGUI8 Content Management System


WebGUI is a mature, feature rich Content Management System. It's written in Perl and licensed under the GNU GPL. Some features include:

  • Hierarchical permissions
  • Groups of groups of groups (etc)
  • Asset versioning
  • A workflow builder that can do things like require two Content Managers to give approval before user submitted content goes online
  • Selectable workflows for new/edited assets
  • Assets create other assets; almost everything is an asset
  • Easily, cleanly extensible OO architecture
  • Discussion boards, shops, image galleries, ticket trackers, and various other types of interactive content
  • Scalable architecture suitable for busy sites


Deploying a Docker Image is the easiest method.

The Source Install process should support any system that supports MariaDB or MySQL, has a semi-recent version of Perl, and is supported by the necessary system libraries (libgd, for example).

Docker Image

An experimental Docker image is available on Docker Hub:

XXX where are they?  Probably don't want to publish these under my name.  Create an org?

See for instructions on installing Docker.

Once Docker is installed, run these commands as root to start WebGUI:

docker pull scrottie/webgui8                    # XXX old image; new one may be at a different location
docker run -p 80:80 scrottie/webgui8:latest     # adding '-t -i' flags runs it interactively

If not run interactively, docker ps -l shows the last Docker container started, docker log <id> shows the output (which will be the plack process output for WebGUI), and docker stop <id> stops it.

Use docker stop <id> to stop the container and docker start <id> to start it again. docker ps -a shows all containers, including stopped ones.

Each time docker run is executed, a new, distinct, persistent copy of WebGUI's database and uploads will be created. Generally, you'll want to only one or a few containers, and then continue to re-start that same one or few. That way, changes you've made in the CMS are persisted.

See for more usage information, and for installation instructions for Windows and Mac OSX.

Please report problems and suggestions for improvements for that in the Docker ticket at or on

Source Installation

Use this manual installation from source for OSX, FreeBSD, and other systems, or for those who like to see exactly what is happening.

You'll need the system packages (dev or source installs of needed libraries) used by wG and the Perl modules wG uses. On Debian, at least the following system packages are needed:

apt-get install
   perl cpanminus libaspell-dev make libdbd-mysql-perl libdigest-perl-md5-perl libxml-simple-perl \
   libmodule-install-perl gcc libperl-dev libmysql++-dev libpng-dev build-essential libgd-dev mariadb-client

This assumes that your site is "". If it's something else, change the commands to match.

Generic source install instructions:

  • Run perl sbin/ to install Perl module deps
  • Create a database named after your site, such as www_whatever_com
  • Load share/create.sql into your MySQL/MariaDB/Percona
  • Copy etc/WebGUI.conf.original to etc/
  • Edit the conf file and set dbuser, dbpass, dsn, uploadsPath (eg to /data/domains/, extrasPath, maintenancePage, and siteName. You can point extrasPath at the existing copy under www/extras if you're only hosting one site on wG. Otherwise, make a per-site copy.
  • Copy the extras directory from whereever you unpacked it to whereever you pointed extrasPath to in the config file.
  • Copy etc/log.conf.original to etc/log.conf
  • Edit etc/log.conf such that log4perl.appender.mainlog.filename points to a writable path. For example: log4perl.appender.mainlog.filename = webgui.log works for local development
  • Set WEBGUI_CONFIG to point at your new config file. For example: export
  • Run upgrades (yes, even for brand new install): wgd reset --upgrade

More detailed (but less well maintained) instructions are in docs/install.txt.

To start WebGUI

To test or develop:

  • Set the PERL5LIB environment variable: export PERL5LIB='/data/WebGUI/lib'
  • Launch it: plackup app.psgi

See docs/install.txt for more detailed installation instructions.

A production site or a dev site that tests sending email or workflows will also need the spectre daemon running.

A proxy server such as nginx or Apache configured to proxy is highly recommended for production sites. The proxy server should serve /extras and /uploads and pass everything else to the plack server process. See docs/install.txt for a recommended plack configuration for production.

Using WebGUI

Developing Applications on top of WebGUI

Community Process

We welcome contributions.

Where things are at:

If you connect to IRC, please be patient.

As a general rule, if you're fixing a bug mentioned in, discuss it at If you're adding a new feature or want to talk about the community process itself, discuss it on

If you're adding a new feature, improving wG, or fixing bugs, please fork

There are plenty of ways to help:

  • Install wG8, test it or just try to use it, and report bugs
  • Discuss ideas for the community process
  • Help update the Wiki
  • Fix bugs
  • Work on code

Fork, make changes in master or in a branch, commit them, push them up, and then use github to send a "pull request". If the request is accepted, your code goes into

Here are some specific tasks to be done:

Rules and process:

  • This fork is run as a (hopefully) benevolent dictatorship, with scrottie having final say on matters
  • For most matters, a rough consensus process between active developers will be used
  • Everyone is welcome to participate provided they are kind to their fellow developers
  • This fork and project are unofficial and not managed by PlainBlack Corp
  • This project exists to support developers and to seek out and include work from different efforts to create a possible base for wG8.1
  • The master branch should be kept in a working state; if you're doing something risky or want to commit something unfinished, please use a branch
  • If you get on IRC, we can help you use git to create branches, fork, and so forth
  • Code included into and developed through this community process may or may not be merged into the official PlainBlack WebGUI at their sole discretion
  • Unit tests are requested where appropriate for code submissions (recommended for most new features and bug fixes) as they're officially required for code committed to official PlainBlack WebGUI
  • To minimize merge conflicts, contributions should not cause undue numbers of changes; please do not reformat code, change whitespace, or make significant number of global replacements except by special arrangement among all concerned
  • I (scrottie) may hand out and revoke commit bits as I deem predudent
  • If you don't have a commit bit, don't worry, just send a pull request from your fork
  • Generally, commit bits may be taken back if you're idle (but can be returned), or if you commit major things to the master branch without to discussion and wind up upsetting people
  • The project is GPL licensed (see for exact terms and conditions); use and modification of this code constitutes agreement to the terms; one of the terms is that code added to the project must also be released as GPL

The Request Cycle

This needs to be moved to a design document.

  • The root level app.psgi file loads all the config files found and loads the site specific psgi file for each, linking them to the proper host names.
  • The site psgi file uses the WEBGUI_CONFIG environment variable to find the config.
  • It instantiates the $wg WebGUI object (one per site).
  • $wg creates and stores the WebGUI::Config (one per site)
  • $wg creates the $app PSGI app code ref (one per site)
  • WebGUI::Middleware::Session is wrapped around $app at the outer-most layer so that it can open and close the $session WebGUI::Session. Any other wG middleware that needs $session should go in between it and $app ($session created one per request)
  • $session creates the $session->user WebGUI::User, $session->request WebGUI::Session::Request, and $session->response WebGUI::Session::Response objects (one per request)
  • lib/ does basic dispatch, first checking for a content handler, and then as a last resort (but the usual case), defaulting to the asset content handler. Content handlers are listed in the config file, in order.
  • The asset content handler, lib/WebGUI/Content/, looks up the asset by URL in the database, creates an instance of the specified class for that asset, and invokes it.


A free open source content management system and web application framework. The most widely deployed mod_perl application on the planet.


You can’t perform that action at this time.