How to upgrade SPIP

Upgrading SPIP to a newer version is very simple. But, follow the recommendations below to avoid any errors.

The following procedure can seem overly complicated, but we have deliberately used as much detail as possible to help you avoid any errors. In practice, upgrading SPIP is quite simple and can be carried out in a few minutes.

1. Backup your database.

Before doing any significant modification to an information processing system, you should always make a backup as a precaution.

Note: this is only a precaution. You are not obliged to do it, and the backup file will certainly not be used for anything if the upgrade proceeds without problems!

It is the same logic as when you upgrade your computer’s operating system (to install a new version of Windows, MacOS or Linux); you backup your important documents, but you know that if the upgrade goes okay, you will not need to reinstall these documents.

This point is significant: backup your database before upgrading, but do not restore it! Indeed, we have noted that many users have backed up their database, carried out the upgrade and then restored their backup; this is an error and their sites displayed errors. The backup is simply a precaution in case of a major problem occurring during the upgrade, but if the operation proceeds normally (which is almost always the case!), you should not restore this backup. (The backup is carried out with the database structure corresponding to the previous version of SPIP; if you restore it after the update, you restore it to a structure which has changed, thus causing problems.)

To make a backup of your database (i.e. of all the documents integrated into SPIP), go in the "Backup/restore the database" page in the private area, and click on the "Backup the database" button.

The FTP authentication procedure starts:

The new page indicates a name for you to copy, in the format "admin_xxxxx". Copy this name, start your FTP client, login to the FTP account that corresponds to your site, and change to the folder /ecrire/data. Create a new file or folder in /ecrire/data with the name copied above (your new file will thus have a name of the form "admin_xxxx").

Once this file has been created, return to the page in your browser and click on the "reload this page" button. The backup is then done.

If you wish to, you can check with your FTP software that the dump.xml (or dump.xml.gz) file was created; this file is the backup of your site. You can leave it on your FTP account, or download it to your own computer.

2. Install the new version of SPIP

The actual upgrade starts here.

The principle is very simple; you just need to install the SPIP files again, exactly as you did for the first installation. You can do this either with "spip_loader" which will perform an automatic installation of the files, or more traditionally by unzipping SPIP on your own hard disk and uploading all the files to your server by FTP.

Note: it is not necessary to remove any files from the previous version. It is neither necessary nor is it advised; indeed, if you remove the old files, you will need to set all of SPIP’s configuration settings again (to set the database connection details, etc), which is a useless procedure if you are satisfied to overwrite the old files with the new ones. By erasing the old files, you are even likely to erase the images contained in your articles! Therefore, keep it simple; don’t erase anything before installing the new files; the new ones will automatically overwrite the old ones...

3. Start the update of your database

Once all the new files have been installed (by FTP, or automatically with "spip_loader"), return in the private area of your site.

Note: make sure you wait until the files are completely installed. If you try to intervene on your site during the file transfer, you will obtain incoherent results.

In your private area, you will see the following message: "Technical Message: the upgrade procedure should be ran to adapt the database to the new version of SPIP. If you are a site administrator, please click on this link".

As an administrator, follow the link to begin the update of the SPIP database. An FTP authentication screen will be displayed, similar to the procedure described above. This is intended to safeguard the database.

Once again, copy the name indicated by this screen and, with your FTP client, create a new directory or file in "ecrire/data" with the name you have just copied.

Click on the "reload this page" button and the database will be updated after which you will be returned to the private area.

That’s it, the upgrade is complete.

Let us repeat our warning, because it is a classic error: Do not restore the database from the backup made earlier. This backup now corresponds to an old database structure, so it is now unusable. If the operation proceeded correctly, you can even destroy this old backup.

In the event of snags!

-  In certain places of the private area (and sometimes on the public site), I obtain error messages such as "file not found", "file missing", or other messages indicating an incomplete or missing file.

There may have been problems transferring your files via FTP. Using your FTP client, check the sizes of the affected files; in particular, if a file has a size of 0 KB, reinstall the file.

-  I obtain many error messages.

Again reinstall all of the files via FTP.

-  My site almost functions correctly, but certain functions do not work, the authors encounter problems whereas administrators do not, etc.

Check the SPIP user’s mailing list. Initially, consult the list archives to see whether your problem has been encountered already. If not, send precise details of your problem to the list, including the following details: which host, version upgraded from/to; do not forget to mention if this problem existed in the previous version. If your problem is a new bug, the developers will work quickly to try to resolve it.