Upgrading to a new version ​
This page is for moving an installed site from one NewsLoop version to a newer one. It covers what an update changes in your database and settings, what you do by hand, and how to go back if something goes wrong.
Your version is shown at the top of System in the admin. What changed in each version is in the Changelog.
Before every upgrade ​
- Read the notes for the new version in Notes for each version below and in the changelog. They list any step you must do yourself.
- Make a backup on the System page (Back up now, with the uploads ticked), and download it. A downloaded copy is safe even if the server fails.
- On a busy site, try it on a copy first, such as a copy at
staging.in front of your domain, or on your computer. - Pick a quiet time. Between uploading the new files and pressing Update the database, some pages may show errors.
How to upgrade ​
You upload the new version over your site, then finish it on the System page. You need no SSH.
-
Make a backup and download it (see Before every upgrade).
-
Download the new version from your CodeCanyon Downloads page, and prepare its
newsloop-webfolder (in Main_File) as in Preparing the files:composer install --no-dev, then the twonpx pnpm@10commands. You need the newvendorandpublic/build: the old ones don't match the new code. -
Upload the prepared files over your site. Keep these, and don't upload the new version's copy of them:
.env(your settings and app key);storage(backups, logs, your translations instorage/app/lang);public/uploads(your pictures and files).
-
Open System in the admin. When the new files bring database changes, it says "The files are newer than the database". Press Update the database. It runs the database changes, publishes the themes' new pictures and styles, and clears the caches.
With SSH you can run these instead, in the site folder:
bashphp artisan migrate --force php artisan newsloop:themes:publish --all php artisan optimize:clear
On a VPS, also see Updates and backups for the permissions and the queue worker.
What an upgrade changes ​
Your database ​
- Database changes run when you press Update the database (step 4 above), or with
php artisan migrate --force. They are Laravel migrations indatabase/migrations, and run once each, in order. - They keep your content. Articles, users, settings, layouts and statistics stay. A migration adds tables and columns, or changes them in place; it never empties a table of your content.
- Skipping versions is fine. Going from 1.0.0 straight to 1.3.0 runs every change in between, in order. You don't need to install each version.
- Big sites: a change to a large table (such as millions of article views) can take a few minutes. Update the database allows up to 15 minutes. On a very large site, run
php artisan migrate --forceover SSH, where there is no time limit.
Your settings and configuration ​
.envis never replaced, as long as you keep your copy, as in step 3.- New settings get sensible defaults. A new version that adds a setting works without it. The admin shows it under Settings, or the version's notes say which
.envline to add if you want to change it. The full list is in the new.env.example. - The
configfolder is replaced. Change settings in.envor in the admin, never inconfig/*.php: edits there are lost at the next update. - On a VPS with cached settings (
php artisan optimize), Update the database clears the cache. Runphp artisan optimizeagain afterwards if you use it.
Your design and files ​
- Uploads,
storageand.envare never touched, as long as you keep them when you upload, as in step 3. Keep your own changes to.htaccessfiles too. - Built-in themes are replaced. Put your design changes in a child theme, which updates leave alone (see Changing a theme's design).
- Changes you made to NewsLoop's own code (in
app,resourcesorroutes) are replaced. Keep a list of them and apply them again, or ask us about a better way. - Your own translations in
storage/app/langare kept (Languages and translations).
The mobile app ​
- Installed apps keep working. The site's API stays at
/api/v1, and a new version never removes or renames anything the app uses. You don't need to release a new app because you updated the site. If an/api/v2ever comes,/api/v1stays alongside it for at least 12 months, so you have time to publish an app update (see Versioning and changes). - Layouts are kept. Your published and draft app layouts stay as they are. The app builder warns you if a new component needs a newer app version.
- To use a new app version (new components or fixes in the app):
- Keep your
whitelabel.yamland your icon and splash pictures from the old app folder. - Copy the new
newsloop-appfolder (in Main_File) to a new place, and put them back. - Run
dart run tool/whitelabel.dart, raise the version, build and upload to the stores as in Building the app. - When most readers have the new version, you can ask the rest to update under App settings → Required update.
- Keep your
After upgrading ​
- Open your site and the admin, and check an article, the home page and the System page.
- On a VPS with a queue worker, restart it so it runs the new code:
sudo supervisorctl restart newsloop-worker. - Press Ctrl + F5 (or Cmd + Shift + R) once if the admin looks wrong: your browser may be showing the old version.
- The cron job and its settings stay as they are.
Going back ​
-
If Update the database fails, nothing else changed. The message says why; see Troubleshooting.
-
To undo an update:
- On System, press Restore on the backup you made before upgrading (see Before every upgrade). It puts the database back.
- Upload the old version's files, prepared as in Preparing the files, keeping
.env,storageandpublic/uploads.
Do both. The old files with the new database (or the new files with the old one) don't match.
Notes for each version ​
The steps you do yourself for each version. Database changes run when you press Update the database, so they are only listed when they need your attention.
| Version | Database | .env and settings |
Steps by hand |
|---|---|---|---|
| 1.0.0 | First release. | — | None. |
Each new version adds a row here and a section to the Changelog.
Troubleshooting ​
- "The database could not be updated". Nothing else changed. The message says which change failed: usually the database user lacks a right such as
ALTER, or the disk is full. Fix that and press the button again, or restore your backup. - "The vendor folder is missing", or an admin without styles, after an update by hand. The new
vendororpublic/buildis missing or old. Run thecomposer installandnpx pnpm@10commands again, and upload both folders. - "500 Server Error" after an update by hand. Open
storage/logs/laravel.log. If it names a missing table or column, the database changes haven't run: open System and press Update the database, or runphp artisan migrate --force. - The admin shows old pages. Clear your browser's cache, and on a VPS run
php artisan optimize:clear.