Before reading any further, please make sure you're actually reading the right version of the documentation, i.e. the one that came with your download.
mwForum should be able to run on any platform with Perl and a webserver.
Perl is usually already installed as part of Unix-like systems. Windows versions are available from ActiveState.
MySQL is the most widely used option. If you want to use PostgreSQL or SQLite, see FAQ.html first, the database installation instructions below are only for MySQL.
DBI and, depending on the chosen database server, DBD::mysql or DBD::Pg or DBD::SQLite can be installed as packages for most Unix-like systems. For ActivePerl on Windows, the modules can be downloaded with ActivePerl's package manager PPM. Most webhosters should have them installed already. Otherwise, they can be downloaded from CPAN.
Every CGI-capable webserver should do the job, though the optimal platform consists of Apache with mod_perl 2.x.
Since the spectrum of possible installation environments is very broad, no installation guide could possibly give exact and foolproof instructions for all existing environments. This problem is aggravated by the fact that both webhosters and Linux packagers almost always make the installation of Perl applications more complicated than that of e.g. PHP applications by the way they set up the webserver.
The example commands below assume an installation performed by a root user using Linux, Apache and MySQL. If your platform differs from that, and it most likely will, you'll have to improvise (or ask your local administrator or guru for help). This is especially true if you don't have shell (aka console or command line) access, but have to configure things using some kind of Web interface and/or FTP client. There are also more specific instructions for some platforms available in the support forum.
shell> cd ~ shell> tar -xzf mwforum-x.x.x.tar.gz
shell> mkdir /usr/local/apache/cgi-bin/mwf/
shell> cp mwforum-x.x.x/script/* /usr/local/apache/cgi-bin/mwf/
shell> chmod 755 /usr/local/apache/cgi-bin/mwf/*.pl
shell> mkdir /usr/local/apache/htdocs/mwf/
shell> cp -r mwforum-x.x.x/data/* /usr/local/apache/htdocs/mwf/
The first two steps assume that you have installed your own MySQL server and have root access. If you're using your provider's database server, skip those two steps. You'll usually need the MySQL root password for these. The MySQL root password is empty by default, but you should change it to something else ASAP. Values that you have to adapt to your specific situation are written in italic.
shell> mysql -e "CREATE DATABASE mwforum CHARSET=utf8"
shell> mysql -e "GRANT ALL ON mwforum.* TO mwforum@localhost IDENTIFIED BY 'password'"
The following features of mwForum require regular execution of the mwForum cronjobs (scheduled tasks, files cron_jobs.pl, cron_subscriptions.pl, cron_bounce.pl and cron_rss.pl). If you don't use any of them, you can skip this section, although the use of the main cronjob (cron_jobs.pl) is highly recommended for the database table defragmentation and optimization alone.
Once again, the actual setup depends on your platform, but the typical installation on a Unix system looks something like the following when executing the main cronjob nightly at 03:10 (don't run it more often than once a day) and the subscriptions cronjob at 03:20. The last line shows an example of how to backup your forum database with mysqldump. See FAQ.html for more info on the feeds cronjob.
# Crontab
10 3 * * * user cd /usr/local/apache/cgi-bin/mwf && perl cron_jobs.pl
20 3 * * * user cd /usr/local/apache/cgi-bin/mwf && perl cron_subscriptions.pl
00 4 * * * user mysqldump mwforum | gzip > ~/mwforum.sql.gz
If your forum is hosted by a provider that doesn't provide cronjobs or similar means of task scheduling, and you want to use any of the above features, you have to either manually start the cronjob(s) on a regular basis, or use the cron emulation feature that starts the main cronjob on the first page request of every day. Cron emulation is enabled with the cronEmu forum option. Either workaround also requires the $cfg->{scriptFsPath} and $cfg->{perlBinary} options in MwfConfig.pm to be set up.
If you intend to run mwForum under plain CGI, or have never heard of mod_perl anyway, you can skip this section. Apache/mod_perl is only necessary for running high traffic sites (as it makes the Perl script execution much faster). mwForum supports mod_perl 1.x (for Apache 1.x) and mod_perl 2.x (for Apache 2.x). Apache 1.x is very old at this point, though, and is not getting tested anymore.
For more information on mod_perl, read its documentation. Installation of mod_perl itself is beyond the scope of this text, the following steps are only those specific to mwForum:
use lib '/usr/local/apache/mwf';" to your
startup.pl (set the path to your script directory), so that the
scripts can find their modules. If you don't use a startup.pl, you
can also add "PerlSwitches -I/usr/local/apache/mwf" to
the Apache configuration instead.
PerlRequire /usr/local/apache/conf/startup.pl
Alias /forum/ /usr/local/apache/forum/
<Location /forum/>
Options +ExecCGI
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
PerlOptions -SetupEnv -ParseHeaders
</Location>
If you want to host multiple forums, see FAQ.html for details.
Any changes to configuration files (and the default forum options in MwfDefaults.pm during upgrades) won't take effect until an Apache reload/restart, even with Apache::Reload or similar enabled for those files.
mwForum has been tested and works with Apache 2.2 on Windows XP and Windows 7, including mod_perl 2.
Depending on your webserver and configuration, you'll usually
have to adjust the "#!/usr/bin/perl" line in all .pl
scripts to something like "#!perl" (if the perl
executable is in the PATH), or
"#!c:\perl\bin\perl.exe" (if not), unless you use
other means of linking .pl files to the Perl interpreter (like
mod_perl). Under Apache 2.x, you might also be able to use the
ScriptInterpreterSource directive.
For configuration options in MwfConfig.pm that are specifying filesystem paths, use forward slashes (c:/forum/) instead of the usual DOS backslashes.
These CGI problems sometimes occur after installation:
This is a generic HTTP error message displayed by the browser
that by itself isn't very helpful. The actual Perl error message
can usually be found in the webserver's error log. If you don't
have access to the error log, you can try adding "use
CGI::Carp qw(fatalsToBrowser);" somewhere near the top of
the script that gives you the 500 error. This will then hopefully
print a more useful error message to the browser. Remove the
CGI::Carp line after resolving the problem.
One of the possible reasons triggering this message is a syntax error in a configuration or language file that you have edited. You can test the syntax of these files by calling "perl -c file.pm".
If you ask about error 500 on the support forum without having found a more specific error message, there isn't much we can do to help you.
This log error message, which usually appears as error 500 in the browser, means that a script has failed before it could print the HTTP headers. Alone, this message is not very helpful either, but it's typically preceded or followed by a more specific error message that points to the real problem.
When there are no additional error messages, this error may also be caused by script files that have been garbled or truncated during upload, or that have the wrong (DOS/Unix) linefeed format. If possible, compare the local and the remote versions of the script to see whether they're the same, or whether the remote script is garbled or truncated. The linefeed format can be converted during upload from DOS to Unix with most FTP programs, or on some servers with "recode l1/cl..l1 *.pm *.pl".
Check the online help page and FAQ.html for more information on features and administration, and ask in the support forum if any questions remain. There is no extensive guide to each and every feature, but who has time to read or write that anyway.