Updating the Nex1on engine and rolling back: how to update calmly

Updating the engine is two actions at once: the files are replaced and the database is brought in order. It is frightening only when there is no way back. In Nex1on there is always a way back: the engine itself makes a database copy and a file restore point, nothing is installed without your word, and if the site does not answer after an update, the previous version can be restored with one press. Below: how to update calmly and what to do if something goes wrong.

How you learn that a new version is out #

If update checks are on, the engine asks nex1on.com once a week whether a new version is out (only the domain, the engine version and the PHP version are sent). If one is, you get an email “Nex1on … is available” (one email per version), and the “System → Updates” page says “Version … is out. Read what changed and decide for yourself”. Nothing is installed by itself: the email only tells you there is something to read. Checks can be turned off: in “Settings → General” set “Check for updates” to “never”.

What the engine does during an update #

The update page goes step by step, and you see each one:

1. It checks the requirements: whether PHP is new enough, whether there is enough free space, and whether the engine's files can be written.
2. It downloads the archive and checks its signature: an archive that does not match the signed hash is not installed.
3. It makes a database copy and a file restore point (a copy is also taken before the database changes are applied). If a copy cannot be made, the update does not start.
4. It replaces the engine's files. While they change, visitors see a “maintenance” page. The config and storage folders are not touched, settings, uploads and data stay as they were, and the old files go into the copy.
5. It applies the database changes (migrations) and checks that the site answers.

Step 1. Prepare #

Open “System → Updates”. Before you press “Update”, do three things.

1. Read what changed. The “Before updating to version …” page shows the description of the version. The full change log lies in the CHANGELOG file in the engine folder.
2. Check the requirements. The engine shows which PHP you have and which is needed, how much free space there is, and whether the engine's files can be written. If something is not met, the “Update” button is off and it says what to fix.
3. Look whether you have edits in the engine's files. If you changed the engine's files, the update replaces them with the release's files and your edits are lost. The page says how many such files there are and offers “Save my changes as an archive”. It is better to keep your changes in your own theme or your own module: an update does not touch them.

Also make a database copy of your own (“System → Backups and transfer → Database backups”): the update takes its own, but the habit of making a copy before any risky step pays off once.

Step 2. Update #

Press “Update”. The page goes step by step and it is best not to disturb it: if you closed the tab, come back to the same page and the update continues from the same place. When all went well the engine says “The engine is updated to version …, the database is in order, the site responds”, and the database copy stays on the “Update” page. If some modules did not update, it says so separately, with the name of the copy.

Step 3. If something goes wrong #

The engine itself checks whether the site answers after the files are replaced. If the answer is wrong, it restores the previous version without you: “The site does not answer properly. Restoring the previous version…”, and then “The previous version has been restored”. You get an email “Update to … was cancelled”. If it could not restore automatically, open the restore page (its address is shown on the update page), enter the key and press “Restore the previous version now”. The previous version's files also lie as an archive in storage/recovery/files.zip. The reason the update did not go through is named plainly:

• The new version needs a newer PHP. Update PHP at the hosting or wait.
• The archive did not match the signed hash. The download was damaged: repeat it.
• The archive is larger than promised or there is not enough space. Free some disk space.
• The update server did not answer or the download broke off. Repeat later.
• The database changes were not applied. Details are in the error log; the copy from before the start is saved.
• A different version came out on the server while you were clicking. Open the update page again.

Updating by hand #

If the server may not write to the engine's files, or you want to update yourself, update by hand: download the archive of the new version from the releases page, unpack it and upload it over the engine's files, leaving config and storage alone. Then open the “Update” section and press “Apply”: the database changes do not apply by themselves. FTP passwords need not be entered in the panel: they are not accepted here and are not stored.

What to check #

• You read the version's description and the list of requirements.
• There are no edits of your own in the engine's files, or if there are, they are saved as an archive.
• There is a fresh database copy and you know where it lies.
• A site key is set in config/local.php (app.key, at least 32 characters): without it a restore is unavailable.
• The restore key is saved until the update is confirmed.
• After the update you opened the home page, a few inner pages and the panel, and “System health” shows no red.

If something goes wrong #

• The “Update” button is off. Meet the requirements listed on the page: the PHP version, the free space, write access to the files.
• “Recovery is unavailable: set a site key”. Put app.key (at least 32 characters) into config/local.php; without it the recovery ticket cannot be signed.
• Recovery is unavailable: the folders storage/recovery and public could not be written to, or the ZIP extension is missing. Give the server write access to these folders and turn ZIP on at the hosting.
• The update broke off halfway. The site may be in a mixed state: press “Restore the previous version now” or use the restore key.
• The new features did not appear. The update page says how many database changes are waiting to be applied: until they are, the site works on the old tables.

What next #

Update by the description, not by habit: read what changed and decide whether you need it now. And make the way back tested, not assumed: one calm day, open the restore page and make sure the site key is in place.