oqapi/webgui
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
webgui/README.md
Joeri de Bruin c6e7012f56 entrypoint script now upgrades
2026-02-25 18:22:11 +01:00

287 lines
8 KiB
Markdown
Raw Permalink Blame History

# 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
Reference in a new issue View git blame Copy permalink