oqapi/webgui
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
webgui/docs/gotcha.txt

508 lines
19 KiB
Text
Raw Blame History

####################################################################
# WebGUI Upgrade Gotchas #
####################################################################
This file contains a list of any changes you should be aware of when
upgrading from one version to the next, or even between multiple
versions. Be sure to heed the warnings contained herein as they will
save you many hours of grief.
6.9.0
--------------------------------------------------------------------
* The If macro has been removed because it's far too dangerous and
error prone. If you use the If macro you may continue to use
it at your own risk, maintenance, and support cost, but it
is no longer supported by Plain Black.
* The session system has been replaced by a new object-oriented one,
which has caused massive API changes. Please consult
migration.txt to bring your custom code up to date with the
new API.
6.8.1
--------------------------------------------------------------------
* Before upgrading you must install the following new Perl modules:
Data::Structure::Util
* Fixed a major versioning system bug in this release where when purging
the last revision of an asset, if it had children, the children were
not purged with it. This may have caused problems in some people's
databases if they used any 6.7.x version or 6.8.0. If it has all you
need to do to fix it is upgrade to this release and then run
sbin/rebuildLineage.pl
6.8.0
--------------------------------------------------------------------
* Before upgrading you must install the following new Perl modules:
DateTime
DateTime::Format::Strptime
DateTime::Cron::Simple
JSON
Finance::Quote
Archive::Zip
And optionally, these:
Test::More
Pod::Coverage
* If you have previously installed the community contributed version
of the In/Out Board (IOB) then you will need to completely
uninstall it before you can proceed with this upgrade.
* The core API has changed. Check docs/migration.txt for details.
* WebGUI now requires Apache2 with mod_perl2 so CGI, FastCGI, PerlEx,
although never officially supported, are no longer possible.
Making this change gave us more than 70% performance improvement
and opens up even more possibilities for performance and other
optimizations.
You'll need to make the following changes in Apache to upgrade
to this release:
Install libapreq2. You can either download and compile this
from the mod_perl web site, CPAN as Apache2::Request, or by
getting the version of the WRE 0.6.0 or higher.
Edit your httpd.conf or httpd.modperl.conf and add the following
directives to your global server config:
LoadModule apreq_module modules/mod_apreq2.so
PerlSetVar WebguiRoot /data/WebGUI
You may also remove this block if you have it:
<Files ~ "\.(pl)$">
SetHandler perl-script
PerlHandler ModPerl::Registry::handler
PerlOptions +ParseHeaders
</Files>
You also no longer need the ExecCGI directive.
Edit each of your virtual hosts and add the following directives,
changing them to suit your needs:
SetHandler perl-script
PerlInitHandler WebGUI
PerlSetVar WebguiConfig www.example.com.conf
If you were using mod rewrite you'll need to adjust your rules
because they no longer need to remove the gateway (index.pl)
from the URL.
If you were using the uploadsAccessHandler.perl you no longer
need that as it is built in to the WebGUI handler.
For more information consult the WebGUI Done Right documentation.
* WebGUI now requires MySQL 5.0 to operate. This is due to the huge
number of new features afforded us in the MySQL 5.0 database,
which will increase performance, and add to our functionality
for the future.
* WebGUI now requires Perl 5.8 to operate.
* The Macro API has been changed. If you have any third-party macros
installed make sure to update them prior to upgrading. See
docs/migration.txt for details.
* You may now optionally create sbin/preload.exclude with a carriage
return seperated list of modules you don't want to be preloaded.
This file requires each line to contain exactly one full module
name such as "WebGUI::Asset::Wobject::WSClient" (without the
quotes) per line. No spaces or additional formatting can be
present. You may, for example, just copy sbin/preload.exclude.example
to sbin/preload.exclude and save yourself about 5MB of memory
because that will eliminate some of the least commonly used
components.
If you mistakenly exclude modules that WebGUI actually needs
to run, it will load them at run time, and just use more RAM,
so you don't need to worry about breaking WebGUI. However, this
doesn't mean you should just exclude everything because doing
runtime loading will likely use 5-10 times more RAM than just
preloading them to begin with.
6.7.0
--------------------------------------------------------------------
* In order to upgrade to 6.7 you must first upgrade to at least 6.6.1.
* The asset API has changed slightly due to versioning, so if you
have any custom assets, check out migration.txt to make
sure they will comply.
* The templates for Survey assets has changed a little. After
upgrading you will notice that your custom view templates
will not display your questions for editing in Admin mode.
You will need to put your questions loop inside of a section
loop. See the default view template for an example.
* If you have any SQL reports going against the asset table, note that
it has been split into two tables "asset" and "assetData" and
your SQL reports will need to change.
* The indexed search asset has been disabled until 6.8 where it will
be entirely rewritten from the ground up.
6.6.4
--------------------------------------------------------------------
* Please ensure you're running HTML::Template version 2.7, which
supports javascript escaping and is needed to ensure js
menus work everywhere. To see what version you're running,
type:
perl -MHTML::Template -e 'print $HTML::Template::VERSION."\n"'
at a command prompt, or alternatively use the
sbin/testEnvironment.pl script included with WebGUI. If
you've had your WebGUI site running on versions prior to 6.4
then you should delete your lib/HTML folder as it contains
an outdated version of HTML::Template.
6.6.3
--------------------------------------------------------------------
* If you created your site using the create.sql script from 6.6.2
you will need to recreate it from the new create.sql script
from 6.6.3. The 6.6.2 version has some unrecoverable
problems in it. If you just upgraded to 6.6.2, you need not
worry, the upgrade is unaffected by this problem.
* If you're randomly getting logged out before upgrading to this
release, clear your browser cache and cookies after upgrading
to this release and the problem will go away.
6.6.0
--------------------------------------------------------------------
* Perl modules that used to be shipped with WebGUI are now required
to be installed on your system manually. You can optionally
just use the WebGUI runtime environment to save yourself
the hassle of downloading all of them. You can also install
them using testEnvironment.pl The new modules you'll need
to install are:
Log::Log4perl
Net::LDAP
Date::Manip
DBIx::FullTextSearch
HTML::Highlight
HTML::TagFilter
HTML::Template
Parse::PlainConfig
Tie::IxHash
Tie::CPHash
XML::RSSLite
XML::Simple
* After upgrading you'll need to create a log.conf file in your etc
folder for the new logger. For most situations you can just copy
log.conf.original to log.conf and you'll be fine. If you want
to set up custom logging rules, see this web page:
http://log4perl.sourceforge.net/releases/Log-Log4perl/docs/html/Log/Log4perl/Config.html
* The Payment plugins should provide two new methods: shippingCost and
shippingDescription. Plugins that do not have these methods
will fatal error when checking out.
* The Commerce/ConfirmCheckout template has a lot of new variables to
use, but also some (existing ones) have been renamed. Please refer
to the corresponding help file.
6.5.6
--------------------------------------------------------------------
* The uploadsAccessHandler.perl script has specific issues with
various versions of mod_perl and Perl CGI due to the many recent
changes in mod_perl and Perl CGI. For this reason it may not work
on your platform. We're working to make a script that will work
everywhere. Until then, using the latest versions of mod_perl and
Perl CGI should produce working results.
6.5.0
--------------------------------------------------------------------
* The International Macro must be enabled in all WebGUI configuration
files for the Help to work correctly.
6.4.0
--------------------------------------------------------------------
* Image Magick is no longer optional.
6.3.0
--------------------------------------------------------------------
* After upgrading your site you'll have to reset the privileges on
your uploads folder to make sure that the web server has
the privileges it needs to write due to a large number of
changes on the filesystem.
* In order to upgrade to 6.3.0 or beyond you need to have already
already upgraded to 6.2.0 or above. The upgrades will fail if
you try to jump from any 6.1 (or prior) version directly to
6.3.
* Your upgrade process will be a little different from here on out.
Use the following steps to do the upgrade:
a) Back up everything.
b) Extract the 6.3 archive over your existing install.
c) Restart apache (don't shut down as normal, just restart).
d) Run upgrade.pl in the sbin folder.
e) Test.
The reason for this is that WebGUI has an innovative new way
of releasing sites for public view as soon as they become
available during the upgrade, even while the other sites are
still being upgraded. Each site will have a maintenance
message displayed until its upgrade is complete.
* The EmptyTrash scheduler plugin has been removed since there's no
need for it with the more useful DeleteExpiredTrash module in
place.
* This upgrade process will run for a very long time and output a
lot of debug information which will be useful if something
goes wrong. You may wish to pipe the debug info to a log
file like this:
perl upgrade.pl --yourcommandlineoptions > /tmp/upgrade.log
* If you're using languages other than English, you'll need to get
new versions of those language files before upgrading. The
language file format has a new requirement. Also, the
language files are now all converted to UTF-8.
* If you were using any non-English language files on your site,
you may now have to convert your site content to UTF-8
format. Check with your language file provider for details.
* If you're upgrading from a release earlier than 5.5.0 then you'll
need to download and upgrade to 5.5.x before you can upgrade
to 6.3 or higher.
* All Site Map wobjects will be migrated to Navigation assets
during the upgrade. All the site map templates will
be lost. If you want them, save them before the upgrade. Also
check your site after the upgrade for all site maps to make
sure that they look the way you want them to look.
* All File Manager wobjects have been migrated to File Folder Layout
assets. The File Manager templates will be deleted during the
upgrade, so if you want to keep yours, get them before upgrading.
* If you have any SQL reports querying internal WebGUI database tables,
you'll need to update them after the upgrade. Most of WebGUI's
database tables will be changed during the upgrade process.
* If you have any custom page templates, they'll need to be updated
to work with the new Layout system. The templates have been
changed significantly enough that automatic migration of them is
not possible.
* You may add optional protection for your uploaded WebGUI files. This
will check the privileges of the files from the WebGUI database
before sending them to the browser. To enable this you must use
these directives:
PerlSetVar WebguiRoot /data/WebGUI
PerlRequire /data/WebGUI/sbin/uploadsAccessHandler.perl
And then add this to each virtual host you wish to protect:
PerlSetVar WebguiConfig www.example.com.conf
<Location /uploads>
PerlAccessHandler WebGUI::UploadsAccessHandler
</Location>
* If you have any custom code, please check out docs/migration.txt as
there have been many changes to the API in this release.
* There are many new components in this release, and as a result many
tables. Here is a list of the new tables. Make sure you have no
plug-ins installed that conflict with this, or tables you've
created for your own uses: Collaboration, Post, Thread,
Post_rating, Post_read, Folder, FileAsset, ITransact_recurringStatus,
ImageAsset, Layout, Shortcut, asset, assetHistory, commerceSettings,
redirect, shoppingCart, snippet, subscription, subscriptionCode,
subscriptionCodeBatch, subscriptionCodeSubscriptions, transaction,
transactionItem
* Due to the sweeping changes in this release the migration script may not
work perfectly on your site. It should get you 90% of the way there,
but it will be up to you to fix the problems it can't catch. Some of
the things to look out for are Collaboration System (formerly USS
and forum) templates. Also look at images and navigations as they've
been moved from outside the content system, to inside it as assets
in the new asset tree.
* If you are using the SMB auth module, please note that it has been removed
from this release. It has been long deprecated and is no longer an
official part of WebGUI. It will be made available in the user
contribs section of plainblack.com for people wishing to continue to
use/maintain it.
6.2.10
--------------------------------------------------------------------
* The recommended default location for the WebGUI log is now
/var/log/webgui.log instead of /data/webgui.log
* The default path for WebGUI backups is now /tmp/backups rather than
/data/backups
6.2.8
--------------------------------------------------------------------
* Due to a bug in the theme system, if you created any themes in any
6.2.x version prior to 6.2.8 they will need to be deleted and
recreated. Otherwise they will export a corrupt theme file.
6.2.2
--------------------------------------------------------------------
* If you used 6.1.1 for a while, and feel like there's something
wrong with your navigation or page tree, then there just
might be. We corrected a rather large problem in the Page
system that could have caused page tree corruption. To test
and fix this problem, get the page tree tools from the user
contribs area of plainblack.com. Be sure to back up your
databases before using this tool.
6.2.0
--------------------------------------------------------------------
* WebGUI now requires Time::HiRes to operate. Be sure to have it
installed prior to upgrading or the the upgrade will fail.
* Parts of the WebGUI API have changed once again, so be sure that
any third-party plug-ins you have installed have been updated
to work with 6.2 before upgrading.
* A new configuration option has been introduced:
exportPath = /path/to/export/dir
If exportPath is defined in the WebGUI config file, a new
"Export" icon will appear in the page toolbar.
6.1.0
--------------------------------------------------------------------
* See docs/migration.txt for changes in plug-in coding.
* You no longer need Data::Serializer.
* See docs/migration.txt for changes in the template system.
* See docs/migration.txt for changes in the Internationalization
and help systems.
* If you're using any third-party plug-ins, you'll need to get
updated versions to work with 6.1.
* If you're using a language other than English on your current site,
you'll need to obtain a language pack from either the user
contributions or one of the WebGUI Worldwide sites.
* Each user's language has been reset to the default language for
the site as specified in the profile settings.
* We removed a bunch of the cryptic-hack code that was allowing
backward compatibility all the way back to some 2.x, 3.x, and
4.x stuff. To be sure that your site will still work, copy
the gateway script (index.pl) over your old one. Also make
sure you have extrasPath and extrasURL defined in your config
file.
* The ThumbnailLinker macro has been removed. You can now use the
Thumbnail macro because it is templated.
6.0.2
--------------------------------------------------------------------
* You need to add all of your site aliases to the sitename variable
in your WebGUI config file.
6.0.1
--------------------------------------------------------------------
* Apache 2.0 is now the recommended web server for WebGUI. As such
sbin/preload.perl has been defaulted for use with mod_perl
2.0. If you are still using Apache 1.3, don't worry, WebGUI
will still work great for you. You just need to edit
sbin/preload.perl to match your environment.
6.0.0
--------------------------------------------------------------------
* As part of the upgrade process our scripts will attempt to
migrate your styles, page, FAQ, Item, Link List, and
SQL Report templates. However, the migration scripts are not
perfect due to the wide-variety of templates out there, so
you may need to update some portions of your templates
manually.
* The Authentication Module API has been completely rewritten.
Please see docs/migration.txt for details.
* The Paginator API has been significantly changed.
Please see docs/migration.txt for details.
* WebGUI now requires the following Perl modules to be installed:
Data::Serializer
SOAP::Lite
Cache::Cache (no longer optional)
WARNING: Be sure you install these modules BEFORE you attempt to
upgrade or the upgrade will fail and you'll have a mess to
clean up!
* If you've created any custom Events Calendar templates, they will
no longer work due to the new template structure for events
calendars. Your old templates will remain intact, however,
so that you can migrate them manually to the new template
variables.
* The Synopsis macro no longer exists. If you were using it to
retrieve the current page's synopsis, then please use the
^Page("synopsis"); macro. If you were using it to build a
synopsis style navigation please use the new ^Navigation();
macro.
* The old navigation system has been entirely replaced. If you've
built or are using any navigation components that did not
come with WebGUI then you'll need to remove them and use
the new configurable navigation system. See migration.txt
for additional details.
* The old realtime search subsystem has been replaced with the new
indexed search wobject. As such, we've removed the ^?; macro.
If you were using the ^?; macro then you'll need to set up
a search wobject to replace it.
* Themes that were created with 5.x versions of WebGUI will fail to
import into WebGUI 6.0. Sometime after the release of 6.0
(gamma) there will be a theme converter available on
plainblack.com to convert your old 5.x themes into 6.0
themes. If you've already imported a 5.x theme you have
nothing to worry about. All of the theme components will
automatically be converted to 6.0.
* If you have any SQL Reports going against any USS, they will need
to be updated as the USS tables have changed.
* During the upgrade process you may see some database errors during
the migration of SQL Reports. Don't be alarmed. Your upgrade
has not failed. Instead, some of the queries in the SQL Reports
may have failed and will cause the SQL Report templates to not
be automatically generated.
Reference in a new issue View git blame Copy permalink