Updating to a new version
The full and update ZIPs, what is never overwritten, the database update from the admin panel or the command line, backups, checks afterwards, going back and moving to another server.
New versions add features and fixes. An update is three things: new files over the old ones, a database update that adds what the new files need, and a short check. This chapter explains the full and the update ZIPs, what an update never overwrites, how to run the database update from the admin panel or the command line, backups, what to check afterwards, and how to go back.
1. The two ZIPs
| File | Contains | Use it for |
|---|---|---|
AIODomain-<version>.zip (the full package) | Everything, including the installer. | A new installation, or moving to a new server. |
AIODomain-<version>-update.zip | The program files, without any file that belongs to your site (see below). | Updating a working installation. |
Both come from your account at lcpanel.com. The Settings → Licence page also shows the newest version, with a Download button when a newer one exists, and the What's New page lists what changed in each release. The marketplace asks for the newest version once a day by itself (job update_check); Check for updates asks at once.
What an update never touches
The update ZIP does not contain:
config.php(your database settings and secret key),installed.lock,- the
data/folder (cache, logs, backups, temporary files), - the
uploads/folder (logos, pictures, identity documents, attachments).
Everything you set in the admin area lives in the database, so settings, pages, categories, menus, e-mail templates, translations you typed and theme options also survive. What an update does overwrite: the program files, the shipped themes (themes/site/horizon and themes/admin/slate), the shipped dictionary languages/bn.dist.json, .htaccess, README.md and CHANGELOG.md.
Because of that:
- Do not edit shipped files. Put your own look in a theme of your own (upload it under Settings → Themes, with its own code) or use the theme options.
- Add words and corrections under Settings → Languages & Translations; they are kept in the database and win over the shipped ones.
- If you changed
.htaccess(for exampleRewriteBase /market/for a sub-folder), apply the same change again after the update.
2. Before you update
- Read What's New for the new version, especially lines starting with Changed or Security.
- Make a backup of the database: Settings → System & Maintenance → Backups → Make a backup now. Download the file to your own computer.
- Copy the files: download
uploads/andconfig.phpfrom the host, or use your hosting panel's backup. The SQL backup does not include uploaded pictures and documents. - Keep the ZIP of the version you run now. It is your way back.
- Switch on Maintenance mode (Settings → General Settings → System) if the marketplace is busy. Visitors see the notice; staff keep working.
- Make sure the cron job is not in the middle of a long run: open the Dashboard and look at the Automation widget.
Updating takes a few minutes. Choose a quiet hour.
3. Update the files
- Upload
AIODomain-<version>-update.zipto the folder of the marketplace with the File Manager or FTP. - Extract it there, and choose to overwrite existing files. The files must land directly in the folder (next to
index.php), not in a new sub-folder. - Delete the ZIP.
The program already running is now the new version, but the database is still the old shape.
4. Run the database update
The database update creates tables the new version needs, adds new columns and settings, and fills in new starting data. It only adds: it never deletes your data, and it is safe to run again.
Open Settings → System & Maintenance. The Database card shows Update needed in orange and the schema version next to the one the code wants. Press Run the database update and confirm. The report appears below the cards, one line per step:
tables all present
done 1.1.0-example - what the step did
schema 1.1.0 - version 1.1.0
A step line starting with FAILED names the step and the error. Read it, fix the cause (often a missing database right or a full disk) and run the update again; steps that already finished are skipped.
If the button is not available (a host that does not let PHP start programs), use one of these instead:
| Way | How |
|---|---|
| Browser | While signed in as an administrator with the Run database updates right, open https://your-domain/db_update.php. It answers in plain text with the same report. Signed out, it answers 403. |
| Command line | php /home/USER/public_html/db_update.php from SSH or a cPanel terminal. No sign-in is needed. |
The card then shows Up to date, and Last update has the time.
5. After the update
Go through this list:
- The footer and the Dashboard Licence widget show the new version number. The Licence page shows Active.
- Settings → System & Maintenance → Log:
errors.logis empty (or has no new lines). Clear it once so a new line is easy to see. - Open the home page, a search, a listing, and the member area in a private window.
- Sign in to the admin area and open a page of each group.
- Run the cron by hand (Run now, Every job, tick Even if not due) and read the output for errors.
- Send a test e-mail from Settings → General Settings → E-mail.
- Clear the cache (it is cleared by the database update, but a second press does no harm).
- Switch Maintenance mode off.
New e-mail templates and settings that a release brings are added by the database update with their default values; yours are never overwritten. Look at Settings once to see whether a new setting needs your choice.
6. Going back
If something is wrong and you cannot fix it quickly:
- Switch on maintenance mode.
- Put the old files back: extract the full package of the previous version over the folder, with overwrite (it does not carry
config.phporinstalled.lock, so they stay). - If the update changed the database in a way the old program cannot use (the release notes say so), restore the SQL backup:
gunzipthe.sql.gzfile and import it into the database with phpMyAdmin or themysqlprogram. The file begins withDROP TABLE IF EXISTSlines, so it replaces the tables. Everything written after the backup is lost, so restore only when you must. - Open the Dashboard and the log; switch maintenance mode off.
Updates only add to the database, so in most cases the previous program version also runs on the updated database. Restore the backup only if you see errors.
7. Moving to another server
- On the old server make a backup and download it, and copy
uploads/and the whole folder. - On Settings → Licence press Release this licence. See The licence key.
- On the new server upload the full package of the same version, extract it, and copy
uploads/back. Create the database and a user, import the SQL backup into it, and write the database name, user, password and host intoconfig.php(copy the old one and change those lines). Make sureinstalled.lockexists. - Point the domain at the new server, enter the licence key on Settings → Licence, and add the cron job.
- Correct Site address under Settings → General Settings → General if the domain changed, press Clear the cache and run the cron by hand.
8. Backups: a routine
| What | How often | How |
|---|---|---|
| SQL backup | Before every update, and weekly | Make a backup now, then Download. Delete old ones to save disk space. |
Files (uploads/, config.php) | Weekly | The hosting panel's backup or a copy over FTP. |
| A test restore | Twice a year | Import a backup into a spare database and open the site against it. A backup nobody tried is a hope, not a backup. |
Backups are named aiodomain-YYYYMMDD-HHMMSS.sql.gz and live in data/backups, which is closed to the web. Anyone with the Backups right can download them; they contain every member's data, so keep them safe.
9. If an update fails
| Problem | Do this |
|---|---|
| White page or 500 after the files | Look at data/logs/errors.log (or the host's error log). Usually a file did not upload completely or a PHP version is too old; upload again. |
| Update needed stays orange | Run the database update again and read the report for FAILED lines. |
db_update.php says 403 | Sign in to the admin area first, as a user with the Run database updates right (the Super Administrator has it), then open it again. |
| The admin sends you to the Licence page | The licence check failed. See The licence key. |
| Styles look broken | Press Clear the cache and reload with Ctrl+F5. |
| You lost customised files | They were overwritten. Restore them from your copy; keep customisations in a theme of your own next time. |