Upgrade your Tiki site

Upgrading Tiki is very similar to its installation. Upgrading is a one-way process. There is no way to downgrade, although you may revert to a previous version by restoring a backup. Before undertaking a major upgrade (e.g. from 6.x to 8.x) perform a test upgrade on a non-production site before proceeding with the real upgrade.

Do I need to upgrade?
It is recommended that you always upgrade to minor versions (e.g. from 7.3 to 7.4) of your current release to remove security vulnerabilities. Some versions of Tiki are listed as Long Term Support which means developers are continuing with security patches and bug fixes on that version for an extended period of time. Minor version upgrades are unlikely to cause problems.

Major upgrades introduce new features, but existing features, themes, plugins and modules may not function as they did before. A test upgrade is strongly recommended.

Do I really need to download and then upload the whole thing using FTP? - For some upgrades a “patch version” is available, if only a few files have been modified. Alternatively, there are some automated scripts which can take care of the upgrade process for you.

Other alternatives to FTP: Rather than downloading and re-uploading the whole package, use commands svn or wget (ask your hosting provider) to move the files directly from SourceForge to your server.

1.1. Determine the version of your current Tiki

You can check by visiting tiki-admin.php?page=general

If you have 3.x or later

You can upgrade directly. Tiki 4.x/5.x/6.x/7x./8.x/9.x/10.x/11.x/12.x include all the database migration scripts to that version. You may wish to manually re-run the installer script for the version you are on, and watch for unexpected errors.

If you have 1.9.x or 2.x

Tiki 1.9.0 was released on 2005-04-27 so it’s unlikely that you still are running one.

From 1.9.0 and more recent to any subsequent version (3.x, 4.x, etc): You can upgrade directly. Tiki 3.x/4.x/5.x/6.x/7x./8.x/9.x includes all the database migration scripts from 1.9.0 to that version. You may wish to manually re-run the installer script for the version you are on, and watch for unexpected errors.

However, if you are having trouble with a database upgrade of anything prior to 3.0 (so including 1.9 and 2.0, especially if it started life before 1.9) it is recommended you upgrade to 3.x (currently 3.8) first and then to your final version.

There is a bug when you upgrade from old versions directly to 9.0 (this is solved in soon-to-be-released 9.1).

If you are upgrading from 1.x releases it is likely that you are also upgrading the version of MySQL. One of the major changes to modern releases of TikiWiki is a change to utf8 encoding. You may experience issues with corrupted text on pages and even the inability to edit pages. One important upgrade step is to skip the default MySQL encoding conversions. If you plan to upgrade by dumping your older MySQL database, moving to a new installation, the restoring the database you may be able to skip Getting out of MySQL Character Set Hell by using the MySQL dump option “--default-character-set=latin1” when dumping the original database. Unless you should also perform the “fix double encoding” step at the very end of the installation unless you change your my.cnf to force utf8 encoding.

If you have 1.6.x or older

You need to run the upgrade scripts for each version, manually or by installing a Tiki of that version.

1.2. About custom themes

Deactivate custom themes: custom themes and custom .tpl files from older versions are unlikely to work and may cause an upgrade failure. Deactivate custom themes by on your new install by changing the name of the active CSS file, so it will not be found by tiki - which causes it to revert to the default theme.

1.3. Determine to which version you want to upgrade to

Keep in mind that Tiki9 and Tiki12 are versions kept as Long Term Support (LTS) and that it’s always safer to upgrade to the latest release in that branch. And it’s always safer to use current stable branch in version x.1 (i.e. 7.1 instead of 7.0) if you are running production sites with extensive usage of many features.

In some cases of new releases (such as 6.3, for instance), you have the option to download and install only the files that have changed (from a compressed file, like: “tikiwiki-inc-6.2-to-6.3.tar.gz”), or to download the full new version (eg. “tikiwiki-6.3.tar.gz”).

1.4. Upgrade through fresh install or Install over existing?

Fresh install (recommended)

You will need to manually move and/or re-integrate any data that is not stored in the MySQL database, for example images and attachments saved as files. This is the recommended process, specially if you have a custom theme style, or one theme style not supported by the new tiki version you are going to use.

Install over existing (NOT recommended for major updates)

This will not delete any Tiki file which was used in previous versions, but are not longer needed. These files shouldn’t do anything except waste a bit of disk space, except for the case of template files (.tpl files under ./templates or subfolders). You can use Security Admin to detect leftover PHP files.

This is not recommended because you are keeping all files from previous tiki versions, which may include old-fashioned tpl files, might conflict with the new version specially in theme styles which have changed or which are not supported any more in the new version of Tiki. That’s why the best option to avoid any potential conflict is to install a new tiki on a new directory, and replace the old one with the new one, plus re-insert the custom files that you need (img/wiki_up, modified tpl files once you now that they are updated to the new Tiki version, etc). See below at “Fresh Install”.

If it’s a minor release (7.1 to 7.2), it’s unlikely to cause any issues because templates don’t change much and there are just bug fixes.

1.5. Create a Backup

1.6. Update your files

Tiki files are distributed in a compressed archive (ex.: .zip). You need to unpack (unzip) the files and upload them to your web server.

Fresh install

Instead of copying over your old files, you can make a fresh install. If you are upgrading to a version previous than Tiki 5.1, you can indicate the database information of your previous Tiki install (info in db/local.php).

Note for Tiki versions after 5.1 (5.3, 6.0, 9.x, 12.x ...):
You are encouraged NOT to manually copy or edit your old local.php into the new site, but let the Tiki installer script (tiki-install.php) create that local.php file when needed in a later step since it will handle properly the former encoding issue for you.

Things that you may need to copy from your old site to your new site:

img/wiki_up folder content (uploaded wiki images)

img/trackers folder content (uploaded images to tracker items)

any customized *.tpl files

any customized styles ( *.css )

any file gallery directories if using the file system to store the files

any image gallery directory if using the file system to save the images

Any customized code

If you make changes which can be useful to others, please consider joining the Tiki community and sharing your enhancements. Beyond helping others, you no longer will need to re-instate and maintain your enhancements at each upgrade. Please see How to get commit access.

Database Collation

In case you are upgrading but in a new server, and thus, you need to create a new database first, please ensure that you create your new database with utf8 collation.

Note: By default, Tiki uses UTF-8 for your database encoding. We strongly encourage you to select “utf8” in the “collation” drop-down box in phpmyadmin (or similar), in the field shown in the following image:

During the upgrade to Tiki 5.1 (or later) through tiki-install.php, Tiki will attempt to do this for you if needed, but in some rare cases Tiki fails to set the collation to utf8, and therefore, you have to do that manually. If the database is already created with latin1 collation, and you want to change that afterwards, you can change the collation through phpmyadmin in the “Operations” tabs once you have selected your database.

Install over existing

To upgrade, copy or upload all the files of the newer version onto the files of the older version so any older ones are replaced (FTP with “overwrite if source is newer”).

Before overwriting the files, remove the non-customized style-specific templates (templates/styles/*, and templates/yoursite/* if any). Previous versions often contained per-style modifications. Those files have since been removed from standard distribution, leaving the old files intact and not taking advantage of enhancements.

Updating via SVN

1.7. Check permissions

. File and Folder permissions

If your server is unhappy with Tiki file and folder permissions (this is dependent on server configuration), you may get an error message or blank pages. These failed attempts are typically in the error log (ask your web host to know where they are as it’s different depending of your setup)

Too few permissions
If a message appears indicating that specific directories are not writable, you will need to change the permissions on the indicated directories. Tiki will attempt to verify that it can read (and write) to all necessary directories. This error message will include instructions about how to resolve the issue.

Too many permissions
If you are getting Internal Server Error 500, blank pages or similar, it could be that the permissions on the files are not appropriate for your webhost.

If your permissions are currently at “777”, use your FTP client to change the files to “755”. If Tiki is installed in a directory, make sure to also change the permission of the folder which contains the tiki files.

If you have shell access, you can run:

sh setup.sh

and answer any questions. If you don’t know what to answer, just click “enter” to keep the defaults.

The option preselected in “Our choice” will initially be “c”, to run “composer” script and get the required php dependencies for you. and in a second step, it will suggest “f”, to fix file and directory permissions (classic default option). You can choose at any time the letter that best suits your needs, among the options offered.

If “sh setup.sh” doesn’t work for you, you may try, in your ./tiki/ directory

Another way is to set permissions for all directories and then set permissions for all files. For example, to set the permissions for all directories to 777 and the permissions for all files to 644, use the following separate commands through shell access:

After correcting any directory or file permission problems, visit tiki-install.php to continue.

. SuPHP Problems

Systems with SuPHP need permissions 755 at maximum. Group must not be allowed to write. This includes the complete path in the filesystem, not only document root of the webserver. Wrong permissions may lead to 500 Internal Server Error here. On the other hand less permissions (namely 750 without x/execute/subdir entry for webserver) may lead to 403 Forbidden Error.

1.1.3. Permission Matrix

Several usecases and minimum to maximum permissions you may try if something doesn’t work properly. Permissions refer to data directly accessed by the webserver (files included by Tiki itself may and should have less permissions):

In English, the above code adds you to the web-server group; forces the tiki tree to be owned by the web-server user and group; and then makes sure the tiki tree is readable and writable by the web-server group (you). Suggestions welcome!

After correcting any directory or file permission problems, visit tiki-install.php to continue.

1.8. tiki-install.php to update your database

(A) Fresh install

On the tiki-install.php page of this new site, connect to the same database as your old site (you can find this info in the file db/local.php of your old site) and follow the instructions to upgrade your site. Make sure to click upgrade and not install, else you wipe out your database.

Note:
For upgrades to versions equal or later than 5.1 (5.3, 6.0, ...), you are encouraged to re-set the connection settings, while keeping the “Force utf-8 connection” option checked, and follow the on-screen instructions.

For upgrades to earlier branches and versions (like any of the Tiki3 LTS branch), you can alternatively just copy db/local.php from your old site to your new site, to avoid entering the information if you wish.

(B) Install over existing

Then, go to tiki-install.php and click the “upgrade” button, which will update the database. Tiki can read your previous db/local.php file and use this information.

Note:
However, for upgrades to versions equal or newer than 5.1 (5.3, 6.0, ...), you are encouraged to re-set the connection settings, while keeping the “Force utf-8 connection” option checked, and follow the on-screen instructions.

If the installer was previously locked (which it should be), you will need to unlock it by deleting db/lock

Security choices during upgrade

There are a couple of important security choices during upgrade/installation as follows:

Secure login

When configuring general settings during installation, there is an option to “Require secure (https) login”. It is recommended to select this option so that data sent between the browser and the site server is kept private.

In order to implement secure logins, in addition to selecting this option, you will need a security certificate and a dedicated IP address for your domain. These can be obtained or purchased from your web hosting company or, in the case of the security certificate, from third parties.

Locking in the installer

In the last step of the installer, the installer is locked by default once you click the button to enter your Tiki. There is an option to elect to not lock the installer in that last step of the installation. It is highly recommended that you lock the installer for any production site. The option is provided for convenience for development sites only. The installer allows a user to change or destroy the site’s database through the browser so it is very important to keep it locked once the installation or up

If the installer fails . . .

On some very old versions of tiki it may be possible that the installer will fail, with an error like this . . .

Fatal Error: Call to a member function fetchRow() on a non-object in (some path)/installer/schema/(some file name here) on line (some number)

This is because perhaps tiki is applying a DB patch to get rid of something that is already gone. Try skipping that file in the upgrade sequence. To do this, you need to insert the filename that produced the error e.g. “20090923_mod_change_directory_defaults_tiki” and a date value (corresponding to the date in the file) as a row in table tiki_schema in your database. Thus the execution of that patch will be skipped by the installer. Try the installer again. You may have to do this with multiple patches.

If you need to fix the encoding issue

Upgrade from previous to 5.1 to 5.1 or newer

Either (A) or (B): fix the encoding issue (5.0 or before -> 5.1 or later)

Previously to Tiki 5.1, some users might have had a double encoding issue in the database of their Tiki. To ensure that this potential problem is fixed for all, if you are upgrading from a Tiki version equal or earlier than 5.0, into some newer Tiki version (5.1, ...5.x; 6.0, 6.x...), you are encouraged to follow once the three steps to fix the issue by means of the tiki-install.php script.

1.8.1.1. Export existing database from earlier releases (

When dumping MySQL databases from earlier versions of TikiWiki you should specify “--default-character-set=latin1 ” to ensure that your MySQL client does not double encode any existing latin1 data.

1.8.1.2. Force connection to utf-8 in db/local.php

Briefly explained above. For the sake of clearness, covered here in detail.

Go to tiki-install.php, and follow steps until step 4: “Set the Database Connection”.

Even if you have a local.php file already there, click on “Modify database connection” instead of “Use Existing Connection”. This will open a form in the lower part of the window for you

Click to enlarge

At the bottom, there will be a section called “Character set”, with a checkbox called “Always force connection to use UTF-8”, that needs to be kept as checked.

Click to enlarge

Fill in your db/local.php details through that form, and click on the “Continue” bottom at the bottom when ready.

Continue to step 5 in the installation process, where you’ll have the opportunity to “Convert database and tables to UTF-8” (see below).

1.8.1.3. Convert database and tables to UTF-8

In step 5 of the installation process, you will be offered the option to “Convert database and tables to UTF-8”, and you will be also shown the current encoding of your database.

Write down the name of the current encoding of your database, because you will need it in the next step below.

Click to enlarge

You can now click on the button “Convert database and tables to UTF-8”.

Once successfully performed, you will not see this option anymore, but just the usual question of whether you want to Re-install the database, or “Automatically upgrade your existing database to” your new Tiki version. Choose this later option, since you are upgrading.

Click to enlarge

(Note: This step is converting you DB collation to utf-8, and your DB tables to use the utf-8 charset also.)

1.8.1.4. Convert content from your previous encoding to utf-8

Finally, you need to convert the content from your existing database (content from wiki pages, etc., but also preferences, which include paths to file and image attachments, like in image galleries, etc.) to utf-8.

To do so, you have an option in the final step under the section “Upgrading and running into encoding issues?”

Click to enlarge

In the dropdown called “Previous table encoding”, choose the one which applies to your case (you wrote it down in the previous step), and click on the button: “Dangerous: Fix double encoding”

Given the nature of this fix, it’s best to do some quick verification of the changes.

Congratulations! You are done.

You can now enter Tiki locking the installer (recommended) or without locking it, and continue using Tiki as normally.

If you have any issues, provide feedback through the usual Support channels.

Alternative: Upgrading your database through shell

Note:
If you upgrade from a version earlier to Tiki 5.1 to a version of Tiki5.1 or newer, you are encouraged to run at least once the tiki-install.php script as explained above, so that you fix the encoding issue that may exist in your database previous to Tiki 5.1.

Assuming you have the command line version of PHP (PHP-CLI), you can simply use the command line version of the installer.

For multi-tiki installations, the dev script can be used. PHP-CLI is still required.

sh doc/devtools/sqlupgrade.sh

If you are updating your database this way instead of tiki-install.php, you should clear your cache (which tiki-install.php does)

1.8.1. Review the Upgrade

Hopefully you see the Upgrade Complete message and there may be a list of operations that failed (common for older versions). If these all say something about a column, row or table that doesn’t exist, you can try ignoring it. Copy and paste the list of errors for future reference, check the ignore boxes and cross your fingers. When in doubt, refer your questions about upgrade errors to the friendly folk on the tiki-develop list.

1.9. Post tiki-install.php

At the end, proceed as usual to the Tiki site while disabling the tiki-install.php script.

1.10. Update the .htaccess file

Tiki ships with a _htaccess file. It needs to be renamed to .htaccess and replace the one from the previous version. If you made any customizations, you should redo them in the new file. See: Apache Clean URLs

1.11. Test

What to expect as problems

Changes in behavior

A feature was activated but no longer is (ex. default behavior has changed). You need to go to the admin panel and activate it.

Bugs

Each Tiki version brings loads of new features. However, sometimes, enhancements can bring new bugs as well

If you customized your themes, they may come out weird

You should plan a bit of time to re-integrate your customizations in the new theme.

If you’ve upgraded your MySQL server from 4 to 5, when you login for the first time, you may get an “Account disabled” error. To repair this:

mysql -u user_dbuser -p user_dbname -B -e "update users_users set waiting=NULL where waiting is not NULL and valid is NULL;"

Where to look

Look in the release notes of your version for any specific things to look for, and to the documentation pages of each new release (i.e. Tiki2, Tiki3, Tiki4, Tiki5, Tiki6 ...)

As of tiki 4, a new system of managing tiki plugins was added to require the authorization of some plugins. Potentially unsafe wiki plugins then had to be validated by users with the new permissions related to approving plugins. If you were using such plugins they will now not function until someone with sufficient permissions approves them.

Now, any user that attempts to use a plugin, including iframe, dbreport, tag, sql, snarf, regex... which would need to be validated by some trusted users/editors/admins later on in order to approve or reject them.

A list of plugin calls pending revision can be found at any time here: tiki-plugins.php

1.12. Upgrade your Theme

Further help?

If you need further instructions, ask in IRC or in the forums, and please, come back here and upgrade the documentation with what you learned. This is a way for you to help and make it easier for new users .

Notes for advanced users

symlinks

When you are happy with the result delete the directory structure of the old site and move the directory of the new site in place. In fact on GNU/Linux or other Unix based servers you can usually use a symlink instead, making the upgrade easy.

ln -s tikiwiki-3.0 tiki

MultiTiki

If you manage many tiki sites in the same tiki instance ( MultiTiki ) but having them in subdirectories, you can follow also the instructions at the Manual Installation page.

Updating via SVN

Tiki Remote Instance manager (TRIM)

Manual Upgrade

Delete Unused Tables

When upgrading, some tables may no longer be used if the related feature has been discontinued. The upgrade script doesn’t delete these extra in case users have data in them they want to keep. You can delete the tables manually if you have access to the database on the server. The following tables are no longer used as of Tiki5:

The 10 galaxia tables

The 4 tiki_chart or tiki_charts tables

tiki_drawings

tiki_newspaper_marks

tiki_newspaper_servers

tiki_quicktags

Shell Commands for swapping versions around

Update 2016 - Got is working this time using the dotglob optionJonny BradleyThu 14 Apr, 2016 17:25 UTC
If you have your new tiki all set up and ready to go in path_to_your_site/tiki15, and a new directory ready to put the old one in called tiki12 for example, here is the command to move everything except them into the tiki12 dir, and then move everything out of tiki15 into your site root: