ShaunSocial docs ShaunSocial user guide
Version 1.5.6
  • 1.5.6 (this version)

ShaunSocial user guide 1.5.6 / Getting started

Upgrade

Admin

This page takes a site that runs an earlier ShaunSocial version to 1.5.6. You back up, replace the files with the new package, and run the upgrade wizard in your browser; your members, posts, settings and uploads stay. Where a step needs a server command, it is in a box marked For your server administrator.

Before you start#

Last updated: 2026-11-17 · v1.5.6

Which versions can be upgraded#

The 1.5.6 upgrade wizard carries the database changes of every earlier version, from 1.0 onward, and applies the ones your site is missing in one run. Upgrading from 1.5.5 or another 1.5 version is the usual case. A site on an older version can be upgraded the same way, but more changes run at once: try it on a copy of the site first (see below).

Check your current version at the bottom of any AdminCP page, next to Current Version.

Checklist#

  1. Check PHP. 1.5.6 needs PHP 8.3 or newer. Earlier ShaunSocial versions also ran on PHP 8.1 or 8.2; if your site still does, have your host switch it to PHP 8.3 first (see Upgrading to 1.5.6).
  2. Download the 1.5.6 package (a zip file) from where you bought ShaunSocial, usually your ShaunSocial client area.
  3. Back up the files and the database. The upgrade changes your database and cannot be undone in the AdminCP: the backup is the only way back. Most control panels have a Backup tool that saves both. Keep the backup until the upgraded site has run well for a few days.

    What you should see: a backup file of your site folder and one of your database, with today's date, saved somewhere other than the server itself.

  4. Write down your plugins. Open AdminCP → Plugins → Manage and note each plugin's name and version, so you can check them after the upgrade (see Plugins).
  5. Try it on a copy first (recommended). If your hosting lets you create a staging or test copy of the site, upgrade the copy first. When it works, upgrade the live site.
  6. Pick a quiet time and switch on maintenance mode (next step).

Switch on maintenance mode#

Maintenance mode shows visitors a message instead of your site while you work. You and your admins can still use the AdminCP.

  1. Open AdminCP → Site Settings → Site Information.
  2. Set Maintenance mode to Offline (Maintenance Mode).
  3. Check Maintenance mode message. Its text after installing reads "We are temporarily offline for upgrading to the latest version, this site will be online soon."
  4. Set Maintenance mode Code to a code of your own (it is 123456 after installing). Anyone who enters this code on the maintenance screen can use the site, so you can check the front end yourself. Do not leave the field empty: with no code, nobody can get past the maintenance screen.
  5. There is no Save button: each setting is saved as soon as you leave the field or pick a choice, and the field turns light yellow.

    What you should see: in a private browser window your site shows the maintenance message.

The Maintenance mode setting set to Offline (Maintenance Mode), with the Maintenance mode Code 123456 and the default maintenance message
AdminCP → Site Settings → Site Information, with Maintenance mode set to Offline. Screenshot taken 2026-11-17.
For your server administrator: backup
mysqldump --single-transaction -u shaunsocial -p shaunsocial > shaunsocial-before-1.5.6.sql
tar -czf shaunsocial-files-before-1.5.6.tar.gz -C /var/www shaunsocial

Use your own database name, user and site folder. The file backup must include the hidden .env file and the whole storage/ folder (uploads, keys, logs). Copy both files off the server.

Upgrade your site#

Last updated: 2026-11-17 · v1.5.6

Step 1: replace the files#

  1. Upload the 1.5.6 zip into your site's folder (the folder that holds .env, not the public folder) and unzip it there, so the new files overwrite the old ones. In most control panels: File Manager → upload → right-click the zip → Extract, and agree to overwrite existing files.
  2. Do not delete the old folder first, and do not delete .env or storage. The package contains no .env and none of your uploads (its storage folder holds only empty folders), so unzipping over your site keeps your settings file, your uploads and your installed plugins. Without .env your site would open the installer again, for anyone.
  3. If you upload with an FTP program, make sure it also uploads hidden files (names that start with a dot, such as public/.htaccess).
  4. Check the version of the new files: open public/version.txt.

    What you should see: 1.5.6.

Until you run the wizard, the site runs the new files on the old database. Go straight on to step 2.

Step 2: run the upgrade wizard#

  1. Open https://example.com/<prefix>/upgrade, with your admin prefix (the start of your AdminCP address), for example https://example.com/admin/upgrade. If you are not signed in to the AdminCP, its sign-in page opens first: sign in with your admin account, then open the upgrade address again if the wizard does not appear by itself.

    What you should see: a page titled Welcome to the ShaunSocial Upgrade with two reminders: back up all files and databases before proceeding, and do not close your browser during the upgrading process.

    The upgrade wizard: Welcome to the ShaunSocial Upgrade, with the reminders to back up all files and databases and not to close the browser, and the Next Step button
    The first wizard screen, with the two reminders and the Next Step button. Screenshot taken 2026-11-17.
  2. Click Next Step.

    What you should see: "Current version your old version | Upgrade version available 1.5.6" and an Install Updates button.

    The upgrade wizard showing Current version 1.5.5 | Upgrade version available 1.5.6 and the Install Updates button
    The second wizard screen, showing the current and the new version. Screenshot taken 2026-11-17.
  3. Click Install Updates once, and wait. The page keeps loading while the wizard changes the database; from an older version this can take several minutes. Do not click again, reload or close the tab.

    What you should see: a green box with the message "Application has been successfully upgraded." and a Go to Home Page button (the browser tab reads Upgrade Finished).

    The upgrade wizard with the green message Application has been successfully upgraded. and the Go to Home Page button
    Upgrade Finished. Screenshot taken 2026-11-17.
  4. Open the AdminCP and look at the bottom of the page.

    What you should see: Current Version: 1.5.6.

Besides the database changes, the wizard adds the new phrases of 1.5.6 to each of your languages (your own translations are kept; new phrases appear in English until you translate them), rebuilds your themes' styles and clears the site's cache. You do not need to do these yourself.

If the screen shows an error message in red with a Click here to exit button instead (the browser tab reads Error! | Site Upgrade), see If something goes wrong. Nothing is marked as upgraded in that case, so you can run the wizard again once the cause is fixed.

For your server administrator: upgrade from the command line

The same upgrade without the browser, useful for a big database or a short web server time limit. In the site folder (after the backup), unzip the package over the site, give the files back to the PHP user, and run the upgrade as that user:

cd /var/www/shaunsocial
unzip -o shaun-core-1.5.6.zip
chown -R www-data:www-data /var/www/shaunsocial
sudo -u www-data php artisan migrate --force --path=/packages/shaunsocial/core/database/migrations
sudo -u www-data php artisan migrate --force --path=/packages/shaunsocial/wallet/database/migrations
sudo -u www-data php artisan migrate --force
sudo -u www-data php artisan shaun_core:update

The three migrate commands apply the database changes in the same order as the wizard and show any error on screen. Run shaun_core:update only after all three migrate commands finished cleanly; if one fails, fix the cause and run it again first. shaun_core:update (silent on success) records the new version, adds the new phrases, rebuilds the themes and clears the cache.

INFO  Running migrations.
...
INFO  Nothing to migrate.

The last migrate may answer Nothing to migrate.: that is fine.

Step 3: after the upgrade#

  1. Check the cron job. Open AdminCP → System Setting → Tasks and wait five minutes.

    What you should see: Succeeded: last on ... with a recent time. If not, see Cron job and queue worker.

  2. Check your plugins. Open AdminCP → Plugins → Manage and compare the list with the one you wrote down. Look under each plugin's name for one of these notes:
    • "Built for an older version of the site and may not display correctly. The plugin still runs — ask its author for an updated build.": upload the version made for 1.5.6 here when you have it.
    • "License of this plugin is not valid for this domain.": the plugin is switched off. See A plugin licence belongs to one domain.
    • A plugin whose status reads Disabled although you never switched it off: it was switched off because the site was opened under another address. Once the site runs under the address the plugin was made for, click Enable on its row; it does not come back by itself.
    What each column and note of the list means is explained in The list of installed plugins.
  3. Check your landing page. The upgrade sets AdminCP → Site Settings → General Configuration → Landing page settings to Designed landing page, the new built-in landing page. If you prefer your previous choice (Default landing page or Custom landing page), select it again and save.
  4. Check your colours. 1.5.6 comes with a new colour palette. In your themes, every colour that still had its old default value is changed to the new default; colours you picked yourself are kept. Your site will look different: review it in AdminCP → Design → Manage Themes and adjust what you want.
  5. Look around the site. Sign in as a member (enter your maintenance code when asked), open the news feed, a profile, chat, and post something with a photo.
  6. Clear your browser's cache if pages look broken or old: press Ctrl+F5 (Cmd+Shift+R on a Mac). If the AdminCP still shows old values, click Clear cache at the top of any AdminCP page.
  7. Switch maintenance mode off: AdminCP → Site Settings → Site Information → Maintenance mode → Online, and save.
  8. If you run the ShaunSocial mobile apps, publish the app version made for 1.5.6 together with this upgrade, and read If you also run the ShaunSocial mobile apps: with any reCAPTCHA option switched on, older app versions can no longer sign members in or up.
For your server administrator: after the upgrade
  • Background queue. Only if .env has SHAUN_QUEUE=true: restart the worker so it runs the new code, and make sure its command serves all five queues, including mail_many. A worker command written for an older version may lack it, and invitations, subscription e-mails and bulk e-mail campaigns then wait forever without an error. The full command is in Background queue.
    php artisan queue:restart
  • Live updates. If Reverb runs on the server, restart it so it uses the new code:
    php artisan reverb:restart
    A process manager such as Supervisor starts it again by itself.
  • Configuration cache. Do not run php artisan config:cache or php artisan optimize (the same warning as for installing: afterwards the AdminCP moves back to /admin, and the upgrade address with it). If one of them was ever run on this site, run php artisan config:clear before opening the wizard.
  • File ownership. Files unzipped as another user (for example root) must be given back to the PHP user, as in the command list above.

What is different when you upgrade to 1.5.6#

Last updated: 2026-11-17 · v1.5.6

WhatWhat to do
PHP 8.3 or newer is required, for the website and for the command line (the cron job runs PHP too)Ask your host to switch your site to PHP 8.3 before you replace the files. On an older PHP the new files do not open at all, and neither does the wizard
1.5.6 is built on a newer version of the framework it runs on (Laravel 13)Nothing, unless someone changed ShaunSocial's own code for you: then that change must be checked against 1.5.6 (see Keeping your customisations)
A new colour palette: theme colours still at their old default values are changed, your own colours are keptReview your themes in AdminCP → Design → Manage Themes (see step 3 above)
The new built-in landing page becomes your landing pageSwitch back in Landing page settings if you prefer your previous choice (see step 3 above)
Plugins built for an older ShaunSocial show a warningThey keep working. Get updated versions from their authors (see step 3 above)
Mobile apps: older app versions are refused while a reCAPTCHA option is onPublish the app version made for 1.5.6, and check the API Secret Key (see step 3 above)
Background queue: one worker must serve five queuesOnly for sites with SHAUN_QUEUE=true (see the server box in step 3)

The new features of 1.5.6 are listed in the release notes.

For your server administrator

PHP 8.3+ for both PHP-FPM and the command line, with the extensions listed in the install requirements. Composer and Node.js are not needed: the package carries its libraries and the built web app, including a fresh bootstrap/cache/packages.php for the new libraries. On cPanel, the cron command must also use PHP 8.3; the command line's php can be a different version than the website's (see Cron job and queue worker).

php -v
PHP 8.3.x (cli) ...

Keeping your customisations#

Last updated: 2026-11-17 · v1.5.6

Everything you change in the AdminCP is stored in your database or in your storage folder, and the upgrade keeps it. Files that come in the package are replaced by the new ones, so changes made directly in those files are lost.

KeptReplaced by the package
  • members, posts, uploads and every other content
  • all AdminCP settings, menus, layouts, static pages and e-mail templates
  • logos and images uploaded in the AdminCP
  • themes made in AdminCP → Design → Manage Themes
  • your languages and your translations (new phrases are added)
  • installed plugins and their data
  • the .env settings file
  • ShaunSocial's program files
  • public/favicon.ico, the app icons in public/images/manifest/ and the default images in public/images/default/
  • public/robots.txt
  • public/.htaccess and .htaccess
  • public/css/custom.css
  1. Before you upgrade, copy any of the files in the right-hand column that you changed yourself, for example your own favicon, a custom robots.txt, extra rules in .htaccess (such as a redirect from www) or your own styles in custom.css.
  2. After the upgrade, put your changes back into the new files. Do not copy whole old files over the new ones without comparing them: the new versions may contain changes of their own.
  3. For your logo, upload it in the AdminCP instead of replacing the file: AdminCP uploads survive every upgrade.
Changes to the program code

If a developer changed ShaunSocial's own code for you, those changes are overwritten. Ask them to apply their changes again on top of 1.5.6, and test on a copy of your site first. Features added as plugins are not affected.

If something goes wrong#

Last updated: 2026-11-17 · v1.5.6

What you seeWhat to do
The upgrade address opens your home page instead of the wizardThe site already counts as upgraded to the version in public/version.txt. Check that file says 1.5.6; if it shows your old version, the new files were not uploaded (repeat step 1). If the AdminCP footer already says Current Version: 1.5.6, there is nothing left to do.
The upgrade address shows "Not found"Use your own admin prefix in the address (the start of your AdminCP address). If even /admin/upgrade does not work, ask your server administrator (see below).
An error message in red and a Click here to exit button after Install Updates (tab title Error! | Site Upgrade)Note the message, click Click here to exit, and send the message to your server administrator or to ShaunSocial support. Once the cause is fixed, open the upgrade address again and click Install Updates again; the wizard runs the changes that are still missing.
The page stops loading or shows a time-out during Install UpdatesOpen the upgrade address again. If the wizard still offers Install Updates, ask your server administrator to finish the upgrade from the command line (see the box in step 2).
The installer opens instead of your siteThe .env file is missing. Restore it from your backup at once: until it is back, anyone could run the installer.
Every page shows an error after replacing the filesUsually PHP is older than 8.3, or files are missing. Check PHP first (What is different), then upload the package again.
Something is badly wrong and you need the old site backRestore both backups, the files and the database, together. Restoring only one of them leaves the site broken.
For your server administrator

Look first at storage/logs/shaun-error-YYYY-MM.log, or the web server's error log when PHP does not start.

SymptomFix
Every page answers 500 with The bootstrap/cache directory must be present and writable.Give bootstrap/cache/ back to the PHP user (chown -R www-data:www-data bootstrap/cache).
The upgrade address is only reachable at /admin/upgrade, or not at allphp artisan config:clear and php artisan route:clear, then try again.
The wizard stops on large sitesRaise PHP's max_execution_time and the web server's time-out for the run, or use the command-line upgrade in step 2.
A migration failsThe error names the table or column. Fix the cause and run the migrate commands again; restore the database backup if you cannot.

Change log#

Last updated: 2026-11-17 · v1.5.6

Date (GMT+7)SectionWhat changed
2026-11-17allFirst version for 1.5.6, written from the 1.5.6 code. The wizard and command-line steps were read from the code, not run.
2026-11-17before-you-startThe maintenance-mode settings save themselves; there is no Save button.
2026-11-17steps, to-1-5-6, troubleshootingCorrections after review: how the wizard's error screen looks, what the package's storage folder holds, the full plugin warning, plugins that stay disabled, the landing page and colour changes of the upgrade, the command-line note.
2026-11-17before-you-start, steps, to-1-5-6Links to the new Plugins and Release notes pages.