Versions and Upgrades

We are constantly working to maintain and improve the LiveWhale platform, and we want you working with the very latest features and bug-fixes! This section describes how to prepare for and execute your LiveWhale upgrade.

Release Notes

You can always see what’s new in the latest version of LiveWhale linked from your upgrades interface, explained below. Or, you can check out a comprehensive list of all the changes since LiveWhale 2.0.0 here.

Version Numbering

Starting with our 2.0.0 release we moved to a system of semantic version numbering using the following guidelines. This allows us to better reflect our ongoing development of LiveWhale by releasing new versions more frequently, as well as making certain that your current version of LiveWhale is numbered to reflect what features/fixes you have in place.

Release type Changes How we’ll number Example
Patch Release Backward compatible bug fixes Increment the third digit 2.0.1
Minor Release Backward compatible new features Increment the second digit, reset last digit to zero 2.1.0
Major Release Changes that might break backward compatibility Increment the first digit, reset other digits to zero 3.0.0

Version Support

LiveWhale upgrades are free with your license agreement. In an effort to encourage using a recent release, we will periodically announce end-of-life dates for support of legacy versions.

Version Initial Release Supported Until
LiveWhale Calendar 1.7.0 October 2019 May 31, 2023
LiveWhale Calendar and Storyteller 1.7.1 December 2020 August 31, 2023
LiveWhale Calendar and Storyteller 2.0.0 June 2022

No end-of-life dates have yet been announced for LiveWhale CMS.

Getting notified of new versions

When a new version of LiveWhale is available, administrators will see the following messaging on the Dashboard of your production sites:

  • For automatic upgrades: “Upgrade scheduled: LiveWhale 2.XX.X (Monday, January 1)”
  • For manual upgrades, before the release date: “New version ready to test: LiveWhale 2.XX.X (Release date: Monday, January 1)”
  • For manual upgrades, after the release date: “New version ready to test and upgrade: LiveWhale 2.XX.X”

You can also sign up to be notified of new versions via email.

Enabling automatic upgrades

You can set up your LiveWhale site to automatically pull the latest release every Sunday morning by following these steps:

  1. SFTP into your server
  2. Edit /livewhale/core/config.php and find the line 'SELF_UPDATE'=>false,
  3. Change that line to 'SELF_UPDATE'=>true, and save config.php
  4. Now, every weekend your site should pull new updates. The first time you log in after each upgrade you will see a “New version installed” message on the dashboard.

You can enable automatic upgrades on dev only, or—if you’re using LiveWhale Calendar—on both dev and prod. See below for further explanation.

When automatic upgrades are enabled…

…on your development site only


Each Sunday morning, LiveWhale will upgrade your dev site to the latest new release (Patch, Minor, or Major) for you to test. After dev has been upgraded, your production site’s LiveWhale dashboard will show a message “Upgrade Available: LiveWhale Calendar 2.x” which you can click to learn more about the new version.

After you’re satisfied with the testing you’ve done on dev, you can follow steps 2–4 below under Upgrading manually to upgrade production.

…on your development and production sites
(LiveWhale Calendar Only)


Each Sunday morning, LiveWhale will upgrade your dev site to the latest new release (Patch, Minor, or Major) for you to test. After dev has been upgraded, your production site’s LiveWhale dashboard will show a message “Upgrade Scheduled: LiveWhale Calendar 2.x (July 2, 2022 at 3am)”. This upgrade is always scheduled for seven days after dev has been upgraded, to give you a chance to glance at what’s new and prepare your editors.

Important: automatic upgrades on production will only pull Patch and Minor releases (i.e., 2.x, only backwards-compatible new features and bug fixes). Major releases (3.0, 4.0, etc.) which correspond to breaking changes will require a manual upgrade on prod, following the below steps.

Upgrading manually

Things to know before you begin:

Note: this process is only available for sites on LiveWhale Cloud Hosting. Please get in touch if you self-host your site and would like to discuss migrating to the cloud.

Step 1: Upgrading your dev server

We often push the new version to your dev server when the release is announced, but, it’s a good idea to check to make sure you’ve got the very latest changes and bug-fixes on dev.

Two ways to do this are:

Setting up automatic upgrades on dev

You can set up your dev server to automatically pull new bug-fixes every week by following these steps:

  1. SFTP into your dev server

  2. Edit /livewhale/core/config.php and find the line 'SELF_UPDATE'=>false,

  3. Change that line to 'SELF_UPDATE'=>true, and save config.php

  4. Now, every weekend your dev server should pull new updates. You can check this by logging in, visiting /livewhale/?lw_debug=1 in your browser and checking the first line LiveWhale Version: 2.0.x (last upgraded MM/DD/YY) to see the last upgraded date.

Manually upgrading dev

Follow these steps to manually pull the latest version to your dev server:

  1. SFTP into your dev server and lock out editors

  2. Login to your dev site at /livewhale/?login (clicking “Click here if you have upgrade access” to bypass the lockout)

  3. Once logged-in, visit /livewhale/?updates_pull and you should see a page that begins something like this:
    Updates pull interface

  4. Double check that the page says “Development server:” and that you are pulling to the correct URL.

  5. Scroll to the bottom of this page and click “Run this update.”

  6. After clicking, wait a minute for the upgrade to run. After you see “Upgrade is complete” or “Server is up-to-date” click the link provided to logout (or visit /livewhale/?logout).

    Note: Some testers reported seeing a white screen here, indicating a server timeout. We’re working on that, but if you see it, simply wait 15–30 seconds and refresh and the upgrade should continue normally.

  7. Log back in to trigger any database upgrades (this may take a few minutes the first time you login after an upgrade)

  8. Once you login and confirm the upgrade has completed, you can remove the editor lockout

Step 2: Syncing recent content to dev for testing

We encourage you to treat all database content on your dev instance— events, images, even groups and users— as disposable. When testing a new version or building a custom feature, we recommend using up-to-date content from your production site. We’ve made it easy to sync live production content to your dev instance.

In LiveWhale 1.7+, you can use this tool to pull updated content to your dev server from the previous night’s backup.

  1. SFTP into your dev server and lock out editors

  2. Login to your dev site at /livewhale/?login (clicking “Click here if you have upgrade access” to bypass the lockout)

  3. Once logged-in, visit /livewhale/?updates_sync and you should see a page that looks like this:
    Content sync interface

  4. Read the instructions carefully and click “Sync Content from …” button when you’re ready to proceed.

  5. You’ll be logged out and brought to a status page. This status page will auto-refresh every minute or two until the sync is complete.

  6. After the sync is complete, you can now remove the editor lockout on dev and test the front- and back-end capabilities with your recent content from prod.

Copying /_ingredients from prod to dev

It’s possible that, over time, some theming changes might have been made on your production server but not on dev. When testing an upgrade, it’s best if your /_ingredients folder on dev and prod begin in sync.

We’re working on automating this process, but in the meantime, we recommend using SFTP to download the entire _ingredients folder from prod and upload it to dev before you begin testing.

This way, any theming changes you make in the next step on dev you can confidently copy to prod in the final step, without worrying about losing prior work.

Step 3: Making changes on dev if needed

You may find that everything works great on dev and nothing needs updating – if so, that’s great, proceed to the final step!

However, you might find that certain customizations or theming on your site requires updating to work with the newest version. Developers comfortable editing HTML/CSS can likely make those changes in-house, but we’re happy to help with that testing or updates on a contract basis.

For example, LiveWhale 1.7.1 introduced Online Events capabilities that you may need to implement in your global theme.
Instructions for making those changes are here.

We recommend making a note of any files in /_ingredients or /livewhale/client/ that you change during this testing step. Then, you’ll know what theme files to copy to prod during your upgrade.

Not sure what to test on dev after your upgrade? We recommend:

  • Back-end
    • Adding/editing an event
    • Trying any new functionality you see in the Release Notes
    • Testing any custom functionality from your site’s backend.less/js or custom modules – not sure if you’ve got any? We can help.
  • Front-end
    • Clicking through day/week/month views
    • Opening an individual event
    • Testing any important widgets on your site

Step 4: Performing the upgrade

After you’re happy with how everything’s working on your dev server, it’s time to schedule your prod (production) upgrade.

Scheduling

We recommend scheduling a 2-hour maintenance window and notifying editors they’ll be locked out, via email or by sending a bulletin. Typically pulling an upgrade takes between 10–45 minutes, but having some cushion time is never a bad thing.

We also suggest notifying us via the Request Help form or your personalized email support address when you’ve scheduled your upgrade window. This will help us keep an eye out in case you require any urgent support during that time.

During your maintenance window

  1. SFTP into your prod server and lock out editors

  2. Login to your prod site at /livewhale/?login (clicking “Click here if you have upgrade access” to bypass the lockout)

  3. Once logged-in, visit /livewhale/?updates_pull

  4. Double check that the page says “Production server:” and that you are pulling to your production site from your dev site.

  5. Scroll to the bottom of this page and click “Run this update”

  6. Since LiveWhale 2.15.2: You’ll be prompted to approve the upgrade, with a reminder of where the release notes can be found and a link to your dev server.

    Modal approval of upgrade
  7. After clicking “Upgrade now,” wait a minute for the upgrade to run. After you see “Upgrade is complete” or “Server is up-to-date” click the link provided to logout (or visit /livewhale/?logout).

    Note: Some testers reported seeing a white screen here, indicating a server timeout. We’re working on that, but if you see it, simply wait 15–30 seconds and refresh and the upgrade should continue normally.

  8. Log back in to trigger any database upgrades (this may take a few minutes the first time you login after an upgrade)

  9. Go back to /livewhale/?updates_pull to double-check that there are no remaining files to pull—if any files are listed, go back to Step 5. If it says “Server is up-to-date,” continue to Step 9.

  10. Using SFTP, copy to prod any changes to /_ingredients or /livewhale/config/ that you made on dev during your testing.

  11. Once you login and confirm the upgrade has completed, you can remove the editor lockout

You’re done! Thanks for using the latest version of LiveWhale, and feel free to let us know how everything went for you. We welcome your feedback on the upgrade process.

On this page