Upgrading Oqtane


By: Shaun Walker

It is recommended that you upgrade Oqtane on a regular basis in order to ensure you are running the latest framework version. Running the latest version provides you with the latest fixes and features, and also helps protect your installation from security vulnerabilities. As a result it is our goal to make the upgrade process as automated and streamlined as possible.

Manual Upgrade

A manual upgrade provides you with the highest level of control over the upgrade process. The detailed steps below are intended to provide the information you need to perform an upgrade.

Step 1 - Download an Upgrade package

- use the following page on Github to access the various releases: https://github.com/oqtane/oqtane.framework/releases
- you will need to download the package for your desired version that ends with *.Upgrade.zip ( ie. Oqtane.Framework.2.0.0.Upgrade.zip )

Step 2 - Navigate to your Installation

- this step will depend on where and how you originally installed Oqtane. You will want to obtain direct access to the root location where the Oqtane framework files were originally deployed. Usually this folder will contain files with a .dll extension ( ie. Oqtane.Server.dll ).

Step 3 - Shutdown your Site

- again this step depends on where and how you originally installed Oqtane. Most web servers or cloud providers provide options through the user interface to stop and start a specific website.
- if you are comfortable with manipulating files directly you can also copy the app_offline.bak from the wwwroot folder in your site to the root folder where the .dll files exist, and change the file extension to .htm ( ie. app_offline.htm ). This will force your website to shutdown temporarily.

Step 4 - Extract the Files

- open the Upgrade.zip package you downloaded previously and extract all of the files to the root location from Step 2.
- *NOTE* many files will already exist from your original installation, so you may need to specify that you want to Replace all existing files in the destination folder ( and usually there is an option to apply this selection to All files ).

Step 5 - Bring you Site back Online

- if you used the web server or cloud provider user interface option in Step 3, use the option to restart your site.
- if you create an app_offline.htm in the root folder, you should delete this file.

Step 6 - Browse to your Site

- open your favorite browser ( ie. Firefox Developer Edition ) and navigate to the Url for the site.
- the system will execute any upgrade scripts automatically during application startup

Automated Upgrade

Oqtane attempts to provide a streamlined upgrade experience for non-technical users.. Simply login to your Oqtane site as the host user and navigate to the Admin Dashboard (via the Control Panel). Choose the System Update option and you will be presented with a screen which has a number of upgrade options.

The default tab will determine if a newer version of Oqtane exists on Nuget.org. If so, it will display a button which says "Upgrade to #.#.#". Clicking this button will download the upgrade package and perform the upgrade automatically. If you are already running the latest version, a message will be displayed indicating this fact.

An Upload tab also exists where it is possible to manually upload a framework upgrade package to the site and then select a button to install it. Using this method also allows you to reinstall/repair an existing installation with the current version.

*NOTE* The automated upgrade is not always successful due to a variety of factors related to your environment. When an automated upgrade fails, you should revert to the Manual method described above.

Do You Want To Be Notified When Blogs Are Published?