Upgrade Guide

This upgrade procedure is about big upgrades. For example when you come from 1.6.x to 2.0.x. If you want to upgrade on the same branch, for example from 2.0.2 to 2.0.9, use the Piwigo Auto Upgrade plugin as described in forum topic Piwigo Auto Upgrade for the impatient.

This procedure is compatible with any version released after 2003 (i.e. release 1.3). For an older version, ask for help on the forum.

Step 1 - Package preparation

Download and unzip the full package (2-3 min).

Once the unzip is complete, delete the 0 bytes file: include/mysql.inc.php (this will prevent you from losing your access parameters).

First and foremost, please do check Piwigo current requirements. Especially if your Php / MySQL configuration is NOT sufficient, do not go further as the upgrade process will fail.

Note: we do NOT recommend using NetInstall for the upgrade processing because it is eventually much more complex than the download of the full package.

Step 2 - Database preparation (Recommended)

Backup your current tables (3-5 min.)

If you are using a version from the PhpWebGallery 1.7 family or later, you can use the DB Backup plugin.
Previous releases users should have to backup their tables by other means, for example with phpMyAdmin [fig. A].

In any case, be sure to check the backup is exhaustive and has successfully completed (the result is sometimes truncated due to server limits).

[Our advice: unselect "Extended inserts" or reduce "Maximal length of created queries".]


[A] PhpMyAdmin recommended options.

Step 3 - File server preparation (Recommended)

Backup your customized files only or all files (5 min.).
Depending on the version you used, some files could not exist.
Minimal files list:
  • include/mysql.inc.php,
  • include/config_local.inc.php ,

Consider this additional files list:

  • template-common/local-layout.css,
  • all your specific theme directories,
  • template/yoga/local-layout.css or any other local-layout.css if you created your own template,
  • your own template (note: phpwebgallery templates are no longer supported by Piwigo anyway),
  • all your *.tpl files from the template-extension directory and sub-directories,
  • all language/.../local.lang.php (conversion of these files in utf-8 format will be required),
  • your personal plugins, if you have some.

Step 4 - Gallery preparation

Lock your gallery (1 min.) [fig. B].
From your current Administration:
Configuration > General > Lock gallery
From now on, non-administrator users of any gallery version should see something like: "The gallery is locked for maintenance. Please, come back later.".

[B] Lock gallery.

Step 5 - Cleaning (Advanced users only)

FTP cleaning (5 min).
Warning : Do NOT delete:
  • galleries directory (maybe some of your pictures are there)
  • upload directory (if you used pLoader, some of your pictures are there)
  • plugins directory (PhpWebGallery from 1.7, or Piwigo from 2.0, to be able to re-use their configuration parameters)
  • theme directories (need to be tested later and maybe turn users to a new one, deleting some active theme will be badly perceived by their users (failures)),
  • template-common and template-extension (they have to be tested).

In anycase do NOT delete or restore immediately:

  • include/mysql.inc.php
  • include/config_local.inc.php

Step 6 - FTP upload

Transfer the new release (5 min.).
Use your standard FTP to upload the new release (Check you have no error).

Step 7 - Database upgrade

Launching upgrade (2 min.).
You don't need to launch the upgrade process if you remain with the same branch, e.g.:
  • Required from PhpWebGallery 1.7.0 to Piwigo 2.0.0, or
  • Required from Piwigo 2.0.0 to Piwigo 2.1.0, but
  • Not required from Piwigo 2.1.1 to Piwigo 2.1.2

So, do not be surprized if you get the message "No upgrade required, the database structure is up to date.", otherwise see [fig. C].

[C] Starting upgrade page.
To avoid any upgrade by another visitor you are invited to sign on.
Your previous release is identified and you will get a summary of the upgrade operations; see [fig. D].
Plugins active before the upgrade will be switched off to inactive status, as they could fail to work with the new release and need their own specific upgrade.

[D] Upgrade memo page.

Step 8 - Check the upgrade result

Your first controls could take time because you are not aware of all the changes (15-120 min.).
You will see a list of all your previous plugins; some of them have been fully integrated in the core (like Plugins Manager), others are now distributed (like LocalFiles Editor), but any desactivated plugin has been so for a good reason.
Try to find an upgrade first; the plugins tabsheets can help you.
For themes and templates, keep an admin page opened in your browser in case you need to reverse any of your tests.
Don't forget that your members or visitors can have a specific selected theme which is not compatible with your new release. You'd probably better have to reset their theme in the Admin users page.

Step 9 - Unlock your gallery

You begin to be confortable with our last release, do not forget to unlock your gallery to give access to visitors (1 min).

Step 10 - Post upgrade cleaning

Nothing (0 min.)
Nothing has to be removed after any upgrade.
The upgrade.php itself is not to be removed.
Remember that the "No upgrade required" message and the sign-on process are protecting your gallery.

Piwigo: "The webmaster's life made easy".