# WebGUI Content Management System

WebGUI is a powerful, open-source content management system and web framework built with Perl. It provides a comprehensive platform for building dynamic websites, managing content, and handling user interactions with a focus on flexibility and extensibility.

## About

- **Version**: 7.10.32
- **Status**: Stable
- **License**: GNU General Public License v2
- **Copyright**: 2001-2009 Plain Black Corporation, and contributors
- **Website**: http://www.plainblack.com

## Features

- **Modular Architecture**: Pluggable asset and component system
- **User Management**: Comprehensive user authentication and group management
- **Content Management**: Flexible asset-based content system
- **Workflow Engine**: Built-in workflow automation
- **Search Capabilities**: Full-text search and indexing
- **API-Driven**: RESTful API support
- **Internationalization**: Multi-language support
- **Commerce Ready**: E-commerce functionality with payment processing
- **Session Management**: Robust session handling and security
- **Caching**: Multiple caching strategies (CHI, FastMmap)
- **Database Abstraction**: Works with MySQL/MariaDB

## System Requirements

### Required Software

- **Perl**: 5.8 or higher
- **Apache**: 2.0+ with mod_perl 2.0 and mod_apreq2
- **MySQL/MariaDB**: 5.0.10 or higher
- **ImageMagick**: 6.0 or higher

### Recommended Modules

A comprehensive list of Perl dependencies is installed via `cpanm` (see Dockerfile for details).

## Quick Start Installation

### 1. Prepare Environment

```bash
# Install Perl 5.8+
# Install Apache 2.0 with mod_perl and mod_apreq2
# Install MySQL/MariaDB 5.0.10+
# Install ImageMagick 6.0+
```

### 2. Configure Apache

Add to your Apache configuration:

```apache
LoadModule apreq_module modules/mod_apreq2.so
LoadModule perl_module modules/mod_perl.so
PerlSetVar WebguiRoot /data/WebGUI
PerlCleanupHandler Apache2::SizeLimit
PerlRequire /data/WebGUI/sbin/preload.perl

<VirtualHost *:80>
    ServerName www.example.com 
    ServerAlias example.com
    DocumentRoot /data/domains/example.com/www
    SetHandler perl-script
    PerlInitHandler WebGUI
    PerlSetVar WebguiConfig www.example.com.conf
</VirtualHost>
```

### 3. Database Setup

```bash
# Create database and user
mysql -e "create database WebGUI"
mysql -e "grant all privileges on WebGUI.* to webgui@localhost identified by 'your_password'"
mysql -e "flush privileges"

# Load schema
mysql -uwebgui -pyour_password WebGUI < docs/create.sql
```

### 4. Configuration

Edit `etc/WebGUI.conf` to match your database and environment settings:

```conf
# Database connection
<database>
    driver=MySQL
    DSN=DBI:mysql:WebGUI:localhost:3306
    username=webgui
    password=your_password
</database>

# Logging
<logging>
    configFile=/data/WebGUI/etc/log.conf
</logging>
```

### 5. Start Services

```bash
# Start MySQL/MariaDB
mysql.server start

# Start Apache
apachectl start
```

## Docker Deployment

WebGUI includes Docker support for easy containerized deployment:

# Build Docker image
```bash
docker build -t webgui:latest .
```

# Run with docker-compose (see distribution/docker-compose.yml)
```bash
cd distribution
docker-compose up -d
```

The Docker setup includes:
- Debian-based container with all dependencies
- Apache 2 with mod_perl
- MariaDB client
- ImageMagick for image processing
- Nginx reverse proxy configuration (distribution/nginx/)

## Project Structure

```
├── lib/                    # Perl modules (main codebase)
│   ├── WebGUI.pm          # Core handler
│   ├── WebGUI/            # WebGUI framework modules
│   ├── WGDev/             # Development utilities
│   └── Spectre/           # Job scheduler
├── sbin/                   # System utilities and scripts
├── t/                      # Test suite
├── etc/                    # Configuration files
├── docs/                   # Documentation
├── distribution/           # Docker and deployment configs
├── www/                    # Web content (uploads, extras)
└── share/                  # Shared resources (nginx config, SQL)
```

### Key Directories

| Directory | Purpose |
|-----------|---------|
| `lib/WebGUI/` | Core WebGUI framework modules |
| `lib/WebGUI/Asset/` | Content asset classes |
| `lib/WebGUI/Form/` | Form field types |
| `lib/WebGUI/Operation/` | Admin operations |
| `sbin/` | Command-line utilities for administration |
| `t/` | Automated test suite |
| `etc/` | Configuration files |
| `docs/` | Installation and reference documentation |

## Development & Testing

### Running Tests

```bash
# Run the complete test suite
perl t/00_compile.t
perl t/Account.t
perl t/Config.t
# ... and many more

# Run specific test
perl t/MyTest.t
```

### Available Utilities

- `sbin/wgd` - WebGUI development tool
- `sbin/spectre.pl` - Job scheduler daemon
- `sbin/upgrade.pl` - Database upgrade utility
- `sbin/testEnvironment.pl` - Environment validation
- `sbin/findBrokenAssets.pl` - Asset consistency checker

## Configuration Files

### Main Configuration
- `etc/WebGUI.conf` - Primary configuration file
- `etc/WebGUI.conf.original` - Original configuration backup

### Logging
- `etc/log.conf` - Logging configuration
- `etc/log.conf.original` - Original logging backup

### Virtual Host Configuration
- `etc/www.example.com.conf` - Example virtual host config
- `distribution/webgui/www.example.com.conf` - Docker example

## Database Schema

The database schema is initialized using:
- `docs/create.sql` - Initial database schema
- `docs/upgrades/` - Version upgrade migration scripts

## Documentation

Detailed documentation is available in the `docs/` directory:

- `install.txt` - Installation instructions
- `changelog/` - Version history and changes
- `credits.txt` - List of contributors
- `legal.txt` - Legal information
- `license.txt` - GPL v2 license text
- `templates.txt` - Template documentation

For more information, visit: [http://wiki.webgui.org](http://wiki.webgui.org)

## Key Components

### Asset System
WebGUI uses an asset-based system for content management where all content types (pages, images, documents, etc.) are assets with configurable properties and workflows.

### Workflow Engine
Automated workflow management for content approval, publishing, and state transitions.

### Session Management
Robust session handling with security features and configuration options for user tracking.

### Commerce
Built-in e-commerce capabilities including:
- Product catalogs
- Shopping carts
- Payment processing (PayPal, Authorize.net)
- Tax calculation

### Search
Full-text search capabilities with indexing for quick content discovery.

## License

WebGUI is released under the **GNU General Public License v2**. See `docs/license.txt` for full license text.

## Credits

WebGUI was created and is maintained by Plain Black Corporation, with contributions from many developers and organizations worldwide. See `docs/credits.txt` for a complete list of contributors.

## Support & Community

- **Main Website**: http://www.plainblack.com
- **Email**: info@plainblack.com
- **Wiki**: http://wiki.webgui.org
- **Installation Guide**: http://wiki.webgui.org/installation-options

## Contributing

Contributions are welcome! Please ensure:
- All tests pass (`perl t/*.t`)
- Code follows Perl best practices
- Changes include appropriate documentation
- Pod comments are included for public APIs

## Troubleshooting

### Database Connection Issues
- Verify MySQL is running: `mysql -uwebgui -p -e "SELECT 1"`
- Check credentials in `etc/WebGUI.conf`
- Verify database user has appropriate privileges

### Apache/mod_perl Issues
- Check Apache error log: `/var/log/apache2/error.log`
- Verify mod_perl and mod_apreq2 are loaded
- Ensure WebguiRoot path is correct

### Missing Dependencies
- Use the Dockerfile as a reference for all dependencies
- Install via cpanm: `cpanm Module::Name`
- Run: `perl sbin/testEnvironment.pl`

## Additional Resources

- Plain Black home: http://www.plainblack.com
- WebGUI Wiki: http://wiki.webgui.org
- Test suite: `t/` directory with comprehensive test coverage
- Configuration examples: `etc/` and `distribution/` directories