History: Upgrade

            ! Upgrade your Tiki site
Upgrading [https://tiki.org|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 ((Backup|restoring a backup)). Before undertaking a major upgrade (e.g. from 21.x to 23.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 22.0 to 22.1) of your current release to __remove security vulnerabilities__.  Some versions of Tiki are listed as ((dev:Version Lifecycle|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.

{BOX(title=>"Overview: How an upgrade works")}
{FANCYLIST()}((Backup)) all the files and database from your current installation. 
Unpack the new version, preferably into a empty folder.
Copy any custom files ~np~(css, uploaded files and images, custom templates) ~/np~from your backup. 
Run the installer ~np~(tiki-install.php) ~/np~which upgrades the database
{FANCYLIST}{BOX}

__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 (tw:1-click installers|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.   

!!# 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.^ 

!!# Determine to which version you want to upgrade to
Keep in mind that ((Tiki21)) and ((Tiki24)) 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. 21.1 instead of 21.0) if you are running production sites with extensive usage of many features.

*((info:Download)) Tiki

!!# 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 (21.1 to 21.2), it's unlikely to cause any issues because templates don't change much and there are just bug fixes.

!!# Create a Backup
You need to backup
# Your entire folder where Tiki is installed (and all subfolders)
# Your MySQL database
See: ((Backup)) for details

!!# 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. 

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 ((dev:How to get commit access)). (:biggrin:)

__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 __utf8mb4 collation__. 
* __Note__: By default, Tiki uses __UTF-8__ (mb4) 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:
+ {img fileId="297" thumb="y" alt="" rel="box[g]"} 


!!! 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 Git or SVN
If you install using Git or SVN, you can easily update with them. See ((dev:Get Code))

!!# Check permissions
{INCLUDE(page="File and folder permissions")}{INCLUDE}

After correcting any directory or file permission problems, visit __tiki-install.php__ to continue. 

!!# 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. 

!!! (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. 

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

!!! 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

!!!- Alternative: Upgrading your database through shell
''Upgrading your database manually through shell (faster than PHPMyAdmin)''

Assuming you have the command line version of PHP (PHP-CLI), you can simply use the command line version of the installer.
{CODE()}
[www]$ php console.php database:update
[www]$
{CODE}


For ((MultiTiki)) installations, the dev script can be used. PHP-CLI is still required.
{CODE()}
[www]$ sh doc/devtools/sqlupgrade.sh
{CODE}
Or:
{CODE()}
[www]$ php console.php database:update --site=site1.example.com
[www]$ php console.php database:update --site=site2.example.com
...
{CODE}

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

!!!# 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. 

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

!!# 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))

!!# Rebuild your search index
Go to the search control panel and rebuild your search index, and it's a good idea usually to clear your Tiki caches. You can find more details ((Search and List from Unified Index|#Rebuild_search_index|here))

!!# 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 (:smile:) 
* 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:{CODE(wrap="1")}mysql -u user_dbuser -p user_dbname -B -e "update users_users set waiting=NULL where waiting is not NULL and valid is NULL;"{CODE}

!!! 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. ((Tiki24)) LTS, ((Tiki25)), ((Tiki26)) LTS, ...)

!!! What to do
* If you need help, visit Tiki chat room ((tw:Chat)) or ((tw:forums))
* If you found a bug, please report it (and fix if you can!) at https://dev.tiki.org

!!!# Check your content
Check if your new web site contains everything from the old website. 

!!!# Check that the features you used to use are still turned on.
More specifically, structures, search, individual plugins, and some other features may have to be activated in the admin panel.

!!!# Revise potentially unsafe plugin calls and approve or reject them.
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__

!!# Upgrade your Theme
Revise the notes at
https://themes.tiki.org/Upgrading

For a more detailed description, read ((Styles and Themes))

!! Further help?
If you need further instructions, ask in the ((tw:Chat)) or in the [https://tiki.org/forum6|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 .

-=Related pages=-
{TITLESEARCH(search=>"Upgrade",noheader="1")/}

!! 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.
{CODE()}ln -s tikiwiki-3.0 tiki{CODE}

!!! 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 Git or SVN
If you have shell access and Git or SVN: dev:((dev:Get Code))

!!! Tiki Manager
If you manage many instances, you should consider the ((Tiki Manager)).

!!! Manual Upgrade
Please see: ((Manual Upgrade))

!!! Upgrade from unmaintained versions
Please see: ((Upgrade from unmaintained versions))

!!! Shell Commands for swapping versions around
''Update 2016 - Got it working this time using the dotglob option'' {sign user="jonnybradley" datetime="2016-04-14T17:25:31+00:00"}
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:
{CODE(colors="shell")}# go to your tiki root
cd path/to/your/tiki/install
#first back everything up off you have room
tar -cvzf ~/backups/htdocs-pre-update-to-15.tar.gz ./
#make a dir to put the old version in while testing
mkdir tiki12
shopt -s dotglob  # sets * to include hidden files
# move all the old files into tiki12
find . -maxdepth 1 -not -name 'tiki12' -not -name 'tiki15' -not -name '.'  -not -name '..' -exec mv {} ./tiki12 \;
# move the new tiki15 site out into the doc root
mv tiki15/* ./
{CODE}