Windows Upgrade Guide

If you already have an installation of Colectica Repository 7.0 or greater and would like to upgrade to a newer version, follow these instructions.

See also

For detailed instructions on first-time installation, see Deployment.

  1. View the current Configure System Prerequisites - Windows to see if any new framework versions are required.

  2. Download the latest :file:` ColecticaRepository-{version}-windows.zip` file.

  3. Before extracting the Colectica Repository and Portal package, make sure Windows does not have the file blocked. To check this:

    1. In Windows Explorer, right click the Zip file and choose Properties.

    2. Near the bottom of the Properties window, in the Security area, see if there is a checkbox labeled Unblock.

    3. If there is an Unblock checkbox, check the box and click OK.

    4. If there is no such checkbox, proceed to the next step.

  4. Stop the Colectica Portal IIS site.

  5. Back up your appsettings.json and files in the Config directory.

  6. Extract the latest ColecticaRepository-version-windows.zip file. Copy the new ColecticaRepository directory contents into your existing ColecticaRepository deployment directory, overwriting all of the existing files.

    Do not delete your existing directory; your existing configuration files will stay in place.

  7. Restart the Colectica Repository IIS site.

  8. Using your browser, test to ensure you have access to the repository and portal.

Upgrading from Releases Earlier than 7.4

  1. Colectica Repository now uses Microsoft dotnet 8. The updated Hosting Bundle can be downloaded from https://dotnet.microsoft.com/download/dotnet/8.0 and should be installed prior to upgrade.

  2. For users on SQL Server, the minimum supported version is now SQL Server 2016. Upgrade to SQL Server 2016 or newer prior to upgrade.

Upgrading from Releases Earlier than 7.2.9461

Colectica Repository now manages the repository database automatically.

  1. If running on Azure PostgreSQL or PostgreSQL prior to version 13, see the Create the Repository Database documentation to allow installing the unaccent extension prior to upgrading the software.

Upgrading from Releases Earlier than 7.0

Colectica Repository and Portal are combined into one installation package. Existing Colectica Portal installations can be directly upgraded to Colectica Repository and Portal 7.0.

Desktop tools including Colectica Designer and Colectica Questionnaires should connect using the REST transport in version 7. The SOAP services have been removed to allow for both Windows and Linux deployments.

  1. The software has been updated to .NET version 6. A new version of the Windows Server Hosting Bundle is needed. The Hosting Bundle can be downloaded from https://dotnet.microsoft.com/download/dotnet/6.0

  2. There are new options in the appsettings.json file. It is recommended that you rename the distributed appsettings.json.dist file to appsettings.json and update the configuration to ensure all the new entries are present.

  3. The default web.config file has been updated, update to the non-Windows or Windows authentication version of the distributed files.

  4. When using Windows authentication, the Windows user and group roles configuration has moved from ConfigRepository.Settings.config to the new windowsauth.settings.json. View the Configure Active Directory documentation.

  5. Any custom language translations or addins should be recompiled using .NET 6. The Localization starter kit has been updated at https://github.com/Colectica/ColecticaPortal.LocalizationStarter for the new .NET version.

  6. The CSS library has been updated to Bootstrap 5. Any custom CSS should be updated to be compatible with the new Bootstrap version.

  7. The Elasticsearch index has been updated. Any existing index should be recreated using the reindex command of the Elastic Indexer. View the Elastic Indexer documentation.

Upgrading from Releases Earlier than 6.2

Starting with version 6.2, a new realtime Elasticsearch indexer is available. If your deployment uses the optional Elasticsearch, view the Elastic Indexer documentation.

Upgrading from Releases Earlier than 6.1

Starting with version 6.0, the setting to enable the REST api has moved from the Admin web page to the appsettings.json. Set the EnableRESTv1 to true to enable the Repository REST api on the Portal.

"API": {
   "EnableRESTv1": "true"
},

Upgrading from Releases Earlier than 6.0

Starting with version 6.0, using a newer .net framework is required.

  1. Colectica Portal requires the .NET Framework SDK 4.7.2 or higher. The NDP472-DevPack-ENU.exe can be downloaded from https://go.microsoft.com/fwlink/?LinkId=874338

  2. The Colectica Portal requires Colectica Repository 6.0 which includes an updated colectica database schema. The Repository database must be updated to version 6.0 for use with Portal version 6.0.

  3. The appsettings.json.dist has several new properties. Please review the new dist file and merge with your existing settings from your appsettings.json backup to create a new appsettings.json incorporating the new properties.

  4. If you are using the optional ElasticSearch indexing, ElasticSearch support was upgraded to version 7.x. You should deploy the latest supported version of ElasticSearch 7 if you are not already using version 7.x. For Elasticsearch installation instructions, please see https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html

Upgrading from Releases Earlier than 5.5.7382

Starting with version 5.5.7382, Portal now uses the netcore 2.2 hosting bundle.

  1. Colectica Portal runs on the netcore 2.2 hosting module in IIS. The dotnet-hosting-2.2.8-win.exe can be downloaded from https://download.visualstudio.microsoft.com/download/pr/ba001109-03c6-45ef-832c-c4dbfdb36e00/e3413f9e47e13f1e4b1b9cf2998bc613/dotnet-hosting-2.2.8-win.exe

Upgrading from Releases Earlier than 5.5.*

Starting with version 5.5, we recommend using a newer .net framework.

  1. Colectica Portal runs best on the .NET Framework SDK 4.7.2 or higher. The NDP472-DevPack-ENU.exe can be downloaded from https://go.microsoft.com/fwlink/?LinkId=874338

Upgrading from Releases Earlier than 5.4.*

Starting with version 5.4, the deployment directory layout changes slightly, and a new dependency is added.

  1. Inside the PortalDir, delete the refs/ directory.

  2. Colectica Portal requires the .NET Framework SDK 4.6.1 or higher. The NDP461-DevPack-KB3105179-ENU.exe can be downloaded from https://www.microsoft.com/en-us/download/details.aspx?id=49978

Upgrading from Releases Earlier than 5.3.6233

Starting with version 5.3.6233, the all Colectica Portal now builds using .NET 4.6.1. Perform these additional steps

  1. Ensure that the Microsoft .NET Framework SDK 4.6.1 or higher is installed. NDP461-DevPack-KB3105179-ENU.exe can be downloaded from https://www.microsoft.com/en-us/download/details.aspx?id=49978.

  2. Ensure that the latest .NET Core Windows Server Hosting Bundle is installed. DotNetCore.1.0.4_1.1.1-WindowsHosting.exe can be downloaded from https://go.microsoft.com/fwlink/?linkid=844461.

  3. If using Postgres, the Postgres connection string has changed slightly and should be updated in the appsettings.json. See the new format in Create the Repository Database

Upgrading from Releases Earlier than 5.2.5635

Starting with version 5.2.5635, the Colectica Portal deployment package uses a simplified folder structure and has some different prerequisites. Follow these steps when upgrading from an earlier version to 5.2.5635 or higher. After upgrading using these steps, subsequent upgrades can be performed using the basic steps above.

  1. Install the .NET Core Windows Server Hosting Bundle. DotNetCore.1.0.4_1.1.1-WindowsHosting.exe can be downloaded from https://go.microsoft.com/fwlink/?linkid=844461

  2. After installing the bundle, execute iisreset at the command line or restart the server to pick up changes to the system PATH.

  3. Instead of overwriting your existing deployment files, deploy the Colectica Portal package to a new location.

  4. From your old location, copy the PortalDir\approot\packages\Colectica.Portal\1.0.0\root\appsettings.json to the root of your new deployment directory.

  5. Edit the Physical Path of your IIS web site to point to the deployment location. This should no longer end in wwwroot like the earlier versions did.

  6. Restart the IIS site and confirm that you can connect to your site using a web browser.

  7. Once you confirm everything is working, you may remove your old deployment files.