How to update it and keep backups

What to back up #

A complete backup is the database together with four items of the installation:

Video tutorial #

Watch Updates and backups on YouTube

• config/app_local.php — the configuration file; it holds this installation's secrets and cannot be regenerated;
• config/installed.php — the installation's record (its version and its installation identifier);
• storage/ — the site's private files (uploads, the installer's and the site's records);
• webroot/media/ — the website's published pictures.

System → Before you go live lists the same set. Keep backups off the server, and keep at least the last few.

How often #

• Every day, the database (most hosting control panels can schedule it).
• Before every update, all of it: the database and the four items above.
• After a large change (new services, an imported customer list, a new theme with new pictures), all of it.

Updating to a new version #

1. Read the new version's changelog (CHANGELOG.html in the package).
2. Back up the database and the four items above.
3. Put the new files in place: replace the installation's files with the new package's Web/ files, keeping your own config/app_local.php, config/installed.php, storage/ and webroot/media/.
4. Run the database changes. Open System → Updates. It shows the Installed version, the Version of these files, the Database and the Waiting database changes:
   • when changes are waiting, tick I have a backup of the database and the files listed above, taken after the last change (an optional note records which backup), then press Run the updates;
   • when the new files bring no database change, press Finish the update to record them as the installed version;
   • "Everything is up to date: no migration is waiting." means there is nothing to do.

On the server, the same is done by php bin/cake.php upgrade migrate --backup-confirmed in the installation's folder. Without --backup-confirmed the command only lists the waiting changes and runs nothing.

1. Check the site: sign in, open the calendar and a job, and look at your homepage.

While the update runs, the site shows a maintenance page. An update also adds the new version's permissions to your roles; a permission you took away from a role stays taken away.

If the update did not complete #

System → Updates then says The update did not complete, and the site stays in maintenance (storage/maintenance.flag): visitors and the administration see the maintenance page. Restore the backup, or correct the cause and run php bin/cake.php upgrade migrate --backup-confirmed on the server again; then delete storage/maintenance.flag.

Restoring #

1. Restore the database from your backup into the installation's database, with your hosting's database tool.
2. Put back config/app_local.php, config/installed.php, storage/ and webroot/media/ from the same backup.
3. If the restore follows a failed update, put back the earlier version's files too, and delete storage/maintenance.flag if it is there.
4. Sign in and check the site.

Always keep config/app_local.php with the database backup: it holds this installation's secrets and cannot be regenerated.