Octopus Deploy Documentation

Upgrading from Octopus 3.x to the latest version

Last updated

You should be safe doing an in-place upgrade of 3.x to the latest version of Octopus Deploy. With that said, the last version of 3.x, 3.17.14, was released on November 12th, 2017. Fundamentally, Octopus is almost an entirely different product. We did our best to maintain backward compatibility, but there is a risk a hyper-specific scenario was missed or a breaking change was introduced. Here is an example of changes made to Octopus Deploy since 3.17.14 was released.

  • The majority of endpoints in the API can accept a Space-Id, for example /api/Spaces-1/projects?skip=0&take=100 whereas before it was /api/projects?skip=0&take=100. If a Space-Id isn't supplied, the default space is used.
  • Teams can be assigned to multiple roles and spaces. Before, a team could be assigned to only one role.
  • Unique internal package feed per space. Each space has a subfolder in the Packages directory to keep them segregated on the file system. Before, a package would be located at C:\Octopus\packages\MyPackage.2020.1.1.zip. Now it is C:\Octopus\packages\Spaces-1\MyPackage.2020.1.1.zip
  • Almost every table in the database had a Space-Id column added to it.
  • Workers were introduced.
  • Azure Management APIs were depreciated.
  • Support for Kubernetes was introduced.
  • Terraform support was introduced.
  • Execution containers running on docker on workers were introduced.

There is some risk involved with doing an in-place upgrade. This guide will walk through the steps needed to reduce the risk and keep downtime to a minimum.

The recommended approach is to create a cloned instance, upgrade that instance, and test out the new functionality with any integrations. From there, you can migrate over to the cloned instance or do an in-place upgrade of your existing instance and use the cloned instance to test future upgrades. This provides the means to test an upgrade without affecting your CI/CD pipeline.

Overview

Creating a clone of an existing instance involves:

  1. Backup the Master Key and license.
  2. Enable maintenance mode on the main instance.
  3. Backup the database of the main instance.
  4. Disable maintenance mode on the main instance.
  5. Restore the backup of the main instance's database as a new database on the desired SQL Server.
  6. Download the same version of Octopus Deploy as your main instance.
  7. Installing that version on a new server and configure it to point to the existing database.
  8. Copying all the files from the backed up folders from the source instance.
  9. Optional: Disable all deployment targets.
  10. Upgrade cloned instance.
  11. Test cloned instance. Verify all API scripts, CI integrations, and deployments work.
  12. If migrating, then migrate over. Otherwise, leave the test instance alone, backup the folders and database, and upgrade the main instance.

Backup the Octopus Master Key

Octopus Deploy uses the Master Key to encrypt and decrypt sensitive values in the Octopus Deploy database. The Master Key is securely stored on the server, not in the database. If the VM hosting Octopus Deploy is somehow destroyed or deleted, the Master Key goes with it.

To view the Master Key, you will need login permissions on the server hosting Octopus Deploy. Once logged in, open up the Octopus Manager and click the view master key button on the left menu.

![](/docs/shared-content/upgrade/images/view-master-key.png “width=500”)

Save the Master Key to a secure location, such as a password manager or a secret manager.

An alternative means of accessing the Master Key is to run the Octopus.Server.exe show-master-key from the command line. Please note: you will need to be running as an administrator to do that.

![](/docs/shared-content/upgrade/images/master-key-command-prompt.png “width=500”)

Backup the License Key

Like the Master Key, the License Key is necessary to restore an existing Octopus Deploy instance. You can access the License Key by going to Configuration ➜ License. If you cannot access your License Key, please contact support@octopus.com and they can help you recover it.

Maintenance Mode

Maintenance mode prevents non-Octopus Administrators from doing deployments or making changes. To enable maintenance mode go to Configuration ➜ Maintenance and click the button Enable Maintenance Mode. To disable maintenance mode, go back to the same page and click on Disable Maintenance Mode.

Backup the SQL Server database

Always back up the database before upgrading Octopus Deploy. The most straightforward backup possible is a full database backup. Execute the below T-SQL command to save a backup to a NAS or file share.

BACKUP DATABASE [OctopusDeploy]
          TO DISK = '\\SomeServer\SomeDrive\OctopusDeploy.bak'
             WITH FORMAT;

The BACKUP DATABASE T-SQL command has dozens of various options. Please refer to Microsoft's Documentation or consult a DBA as to which options you should use.

Restore Backup of database

Use SQL Server Management Studio's (SSMS) built-in restore backup functionality. SSMS provides a wizard to make this process as pain-free as possible. Be sure to consult a DBA or read up on Microsoft's Documentation.

Downloading the same version of Octopus Deploy

The migration tool requires both the main instance and test instance are on the same version. You can find the version you are running by clicking on your name in the top right corner of your Octopus Deploy instance.

![](/docs/shared-content/upgrade/images/find-current-version.png “width=500”)

You can find all the previous versions on the previous versions download page.

Installing Octopus Deploy

Run the MSI you downloaded to install Octopus Deploy. Once the MSI is finished, the Octopus Manager will automatically launch. Follow the wizard, and on the section where you configure the database, select the pre-existing database.

![](/docs/shared-content/upgrade/images/select-existing-database.png “width=500”)

Selecting an existing database will ask you to enter the Master Key.

![](/docs/shared-content/upgrade/images/enter-master-key.png “width=500”)

Enter the Master Key you backed up earlier, and the manager will verify the connection works.

Finish the wizard, keep an eye on each setting to ensure you match your main instance. For example, if your main instance uses Active Directory, your cloned instance should also be configured to use Active Directory. After the wizard is finished and the instance is configured, log in to the cloned instance to ensure your credentials still work.

Copy all the files from the main instance

After the instance has been created, copy all the contents from the following folders.

  • Artifacts, the default is C:\Octopus\Artifacts
  • Packages, the default is C:\Octopus\Packages
  • Tasklogs, the default is C:\Octopus\Tasklogs

Failure to copy over files will result in:

  • Empty deployment screens
  • Missing packages on the internal package feed
  • Missing project or tenant images
  • And more

Disabling All Targets - Optional

Cloning an instance includes cloning all certificates. Assuming you are not using polling Tentacles, all the deployments will "just work." That is by design if the VM hosting Octopus Deploy is lost and you have to restore Octopus Deploy from a backup.

Just working does have a downside, as you might have triggers, auto release creation, and other items configured. These items could potentially perform deployments. The safest thing to do is to disable all the targets. You can find a script on how to do that in the API Examples section.

Octopus Deploy components

Before performing an in-place upgrade, it is essential to note the various components of Octopus Deploy. Most in-place upgrades will only change the install location and the SQL Server database. Very rarely will an in-place upgrade change the home folder or server folders.

The Windows Service is split across multiple folders to make upgrading easy and low risk.

  • Install Location: By default, the install location for Octopus on Windows is C:\Program Files\Octopus Deploy\Octopus. The install location contains the binaries for Octopus Deploy and is updated by the MSI.
  • SQL Server Database: Since Octopus Deploy 3.x, the back-end database has been SQL Server. Each update can contain 0 to N database scripts embedded in a .dll in the install location. The Octopus Manager invokes those database scripts automatically.
  • Home Folder: The home folder stores configuration, logs, and other items unique to your instance. The home folder is separate from the install location to make it easier to upgrade, downgrade, uninstall/reinstall without affecting your instance. The default location of the home folder is C:\Octopus. Except in rare cases, this folder is left unchanged by the upgrade process.
  • Instance Information: The Octopus Deploy Manager allows you to configure 1 to N instances per Windows Server. The Octopus Manager stores a list of all the instances in the C:\ProgramData\Octopus\OctopusServer\Instances folder. Except in rare cases, this folder is left unchanged by the upgrade process.
  • Server Folders: Logs, artifacts, and packages are too big for Octopus Deploy to store in a SQL Server database. The server folders are subfolders in C:\Octopus\. Except in rare cases, these folders are left unchanged by an upgrade.
  • Tentacles: Octopus Deploy connects to deployment targets via the Tentacle service. Each version of Octopus Deploy includes a specific Tentacle version. Tentacle upgrades do not occur until after the Octopus Deploy server is upgraded. Tentacle upgrades are optional; any Tentacle greater than 4.x will work with any modern version of Octopus Deploy. We recommend you upgrade them to get the latest bug fixes and security patches when convenient.
  • Calamari: The Tentacles facilitate communication between Octopus Deploy and the deployment targets. Calamari is the software that does the actual deployments. Calamari and Octopus Deploy are coupled together. Calamari is upgraded automatically during the first deployment to a target.components.

Install the newer version of Octopus Deploy

Installing a newer version of Octopus Deploy is as simple as running MSI and following the wizard. The MSI will copy all the binaries to the install location. Once the MSI is complete, it will automatically launch the Octopus Manager.

Validation Checks

Octopus Deploy will perform validation checks before upgrading the database. These validation checks include (but are not limited to):

  • Verify the current license will work with the upgraded version.
  • Verify the current version of SQL Server is supported.

If the validation checks fail, don't worry, install the previously installed version of Octopus Deploy, and you will be back up and running quickly.

Database Upgrades

Each release of Octopus Deploy contains 0 to N database scripts to upgrade the database. The scripts are run in a transaction; when an error occurs, the transaction is rolled back. If a rollback does happen, gather the logs and send them to support@octopus.com for troubleshooting. You can install the previous version to get your CI/CD pipeline back up and running.

Testing the upgraded instance

It is up to you to decide on the level of testing you wish to perform on your upgraded instance. At a bare minimum, you should:

  • Do test deployments on projects representative of your instance. For example, if you have IIS deployments, do some IIS deployments. If you have Java deployments, do some Java deployments.
  • Check previous deployments, ensure all the logs and artifacts appear.
  • Ensure all the project and tenant images appear.
  • Run any custom API scripts to ensure they still work.
  • Verify a handful of users can log in, and that their permissions are similar to before.
  • Build server integration; ensure all existing build servers can push to the upgraded server.

We do our best to ensure backward compatibility, but it impossible to cover every user scenario for every possible configuration. If something isn't working, please capture all relevant screenshots and logs and send them over to support@octopus.com for further investigation.

Migrating to a new instance

It will be possible to run both the old and cloned instances side by side. Both of them can deploy to the same targets (assuming you are not using polling Tentacles). But there are a few items to keep in mind.

  • The Octopus Server is tightly coupled with Calamari. Deploying to the same target from both servers will result in Calamari getting upgraded/downgraded a lot.
  • The newer Octopus Server will prompt you to upgrade the Tentacles. While running both instances side by side, you will want to avoid this.
  • Unless the cloned instance has the same domain name, polling Tentacles will not connect to the cloned instance. A clone of the polling Tentacles might need to be created.
  • The thumbprints for certificates and other sensitive items are stored in the Octopus Deploy database. Cloning the database cloned those values.

Considerations

As you migrate your instance, here are few items to consider.

  1. Will the new instance's domain name be the same, or will it change? For example, will it change from https://octopusdeploy.mydomain.com to https://octopus.mydomain.com. If it changes and you are using polling Tentacles, you will need to create new Tentacle instances for the new Octopus Deploy instance.
  2. What CI, or build servers, integrate with Octopus Deploy? Do those plug-ins need to be updated? You can find several of the plug-ins on the downloads page.
  3. Do you have any internally developed tools or scripts that invoke the Octopus API? We've done our best to maintain backward compatibility, but there might be some changes.
  4. What components do you use the most? What does a testing plan look like?
  5. Chances are there are new features and functionality you haven't been exposed to. How will you train people on the new functionality? If unsure, reach out to advice@octopus.com and to get pointed in the right direction.

Drift concerns

While it is possible to run two instances side by side, each minute that passes, the two instances will drift further apart. Changes to the deployment process, new packages, new and releases deployments will be happening during this time.

If you find yourself needing more time than a few days, a week tops, consider setting up a test instance. Or using this newly cloned instance as a test instance. Work out all the kinks on the test instance, then restart the cloning process on a fresh instance.

If you are unsure how long the migration will take, consider setting up a test instance first. Work out all the kinks, then start the cloning process.

Polling Tentacles

A Polling Tentacle can only connect to one Octopus Deploy instance. It connects via DNS name or IP address. If the new instance's DNS name changes - for example, the old instance was https://octopusdeploy.mydomain.com with the new instance set to https://octopus.mydomain.com - you'll need to clone each Polling Tentacle instance.

Each Polling Tentacle will need to be cloned on each deployment target. To make things easier, we have provided this script to help clone a Tentacle instance. That script will look at the source instance, determine the roles, environments, and tenants, then create a cloned Tentacle and register that cloned Tentacle with your cloned instance.

Any script that clones a Tentacle instance must be run on the deployment target. It cannot be run on your development machine.

Executing the cutover

Cutting over from the old instance to the new instance will require a bit of downtime and should be done off hours.

  1. Enable maintenance mode on the old instance to put it into read-only mode.
  2. Ensure all CI servers are pointing to the new instance (or change DNS).
  3. You don't have to upgrade Tentacles right away. Newer versions of Octopus Deploy can communicate with older versions of Tentacles. You can upgrade a set at a time instead of upgrading everything, starting in 2020.x you can perform a search on the deployment target page and update only the returned Tentacles. Or, you can upgrade Tentacles per environment.

Backup the server folders

The server folders store large binary data outside of the database. By default, the location is C:\Octopus. If you have High Availability configured, they will likely be stored on a NAS or some other file share.

  • Packages: The default location is C:\Octopus\Packages\. It stores all the packages in the internal feed.
  • Artifacts: The default location is C:\Octopus\Artifacts. It stores all the artifacts collected during a deployment along with project images.
  • Tasklogs: The default location is C:\Octopus\Tasklogs. It stores all the deployment logs.

Any standard file-backup tool will work, even RoboCopy. Very rarely will an upgrade change these folders. The release notes will indicate if these folders are going to be modified.

In-place upgrade of the main instance

Upgrading your main Octopus Deploy instance should follow the same steps you did with the test or cloned instance. Don't forget to run your backups!

Alternative approach - create a test instance

Creating and migrating to a cloned instance can be quite a bit of work. You have to worry about drift and getting new compute resources allocated. An alternative approach to the cloned instance is creating a test instance with only a handful of projects. Test the upgrade with that test instance and then do the upgrade of your main instance.

Overview

The steps for this are:

  1. Backup the Master Key and license.
  2. Download the same version of Octopus Deploy as your main instance.
  3. Install Octopus Deploy on a new VM.
  4. Export a subset of projects from the main instance.
  5. Import that subset of projects to the test instance.
  6. Download the latest version of Octopus Deploy.
  7. Backup the test instance database.
  8. Upgrade that test instance to the latest version of Octopus Deploy.
  9. Test and verify the test instance.
  10. Enable maintenance mode on the main instance.
  11. Backup the database on the main instance.
  12. Backup all the folders on the main instance.
  13. Do an in-place upgrade of your main instance.
  14. Test the upgraded main instance.
  15. Disable maintenance mode.

Backup the Octopus Master Key

Octopus Deploy uses the Master Key to encrypt and decrypt sensitive values in the Octopus Deploy database. The Master Key is securely stored on the server, not in the database. If the VM hosting Octopus Deploy is somehow destroyed or deleted, the Master Key goes with it.

To view the Master Key, you will need login permissions on the server hosting Octopus Deploy. Once logged in, open up the Octopus Manager and click the view master key button on the left menu.

![](/docs/shared-content/upgrade/images/view-master-key.png “width=500”)

Save the Master Key to a secure location, such as a password manager or a secret manager.

An alternative means of accessing the Master Key is to run the Octopus.Server.exe show-master-key from the command line. Please note: you will need to be running as an administrator to do that.

![](/docs/shared-content/upgrade/images/master-key-command-prompt.png “width=500”)

Backup the License Key

Like the Master Key, the License Key is necessary to restore an existing Octopus Deploy instance. You can access the License Key by going to Configuration ➜ License. If you cannot access your License Key, please contact support@octopus.com and they can help you recover it.

Downloading the same version of Octopus Deploy

The migration tool requires both the main instance and test instance are on the same version. You can find the version you are running by clicking on your name in the top right corner of your Octopus Deploy instance.

![](/docs/shared-content/upgrade/images/find-current-version.png “width=500”)

You can find all the previous versions on the previous versions download page.

Installing Octopus Deploy

Run the MSI you downloaded to install Octopus Deploy. After you install Octopus Deploy, the Octopus Manager will automatically launch. Follow the wizard. A few notes:

  1. You can reuse your same license key on up to three unique instances of Octopus Deploy. We determine uniqueness based on the database it connects to. If you are going to exceed the three instance limit, please reach out to advice@octopus.com to discuss options.
  2. Create a new database for this test instance. Restoring a backup will cause Octopus to treat this as a cloned instance, with the same targets, certificates, and keys.
  3. Run the test instance database on the same version of SQL Server as the main instance. Only deviate when you plan on upgrading SQL Server.

Export subset of projects

All versions of Octopus Deploy since version 3.x has included a data migration tool. The Octopus Manager only allows for the migration of all the data. We only need a subset of data. Use the partial export command-line option to export a subset of projects.

Run this command for each project you wish to export on the main, or production, instance. Create a new folder per project:

Octopus.Migrator.exe partial-export --instance=OctopusServer --project=AcmeWebStore --password=5uper5ecret --directory=C:\Temp\AcmeWebStore --ignore-history --ignore-deployments --ignore-machines

This command ignores all deployment targets to prevent your test instance and your main instance from deploying to the same targets.

Import subset of projects

The data migration tool also includes import functionality. First, copy all the project folders from the main instance to the test instance. Then run this command for each project:

Octopus.Migrator.exe import --instance=OctopusServer --password=5uper5ecret --directory=C:\Temp\AcmeWebStore

Downloading the latest version of Octopus Deploy

The downloads page will always have the latest version of Octopus Deploy. If company policy dictates you install an older version, for example, the latest version is 2020.4.11, but you can only download 2020.3.x, then visit the previous downloads page.

Maintenance Mode

Maintenance mode prevents non-Octopus Administrators from doing deployments or making changes. To enable maintenance mode go to Configuration ➜ Maintenance and click the button Enable Maintenance Mode. To disable maintenance mode, go back to the same page and click on Disable Maintenance Mode.

Backup the SQL Server database

Always back up the database before upgrading Octopus Deploy. The most straightforward backup possible is a full database backup. Execute the below T-SQL command to save a backup to a NAS or file share.

BACKUP DATABASE [OctopusDeploy]
          TO DISK = '\\SomeServer\SomeDrive\OctopusDeploy.bak'
             WITH FORMAT;

The BACKUP DATABASE T-SQL command has dozens of various options. Please refer to Microsoft's Documentation or consult a DBA as to which options you should use.

Octopus Deploy components

Before performing an in-place upgrade, it is essential to note the various components of Octopus Deploy. Most in-place upgrades will only change the install location and the SQL Server database. Very rarely will an in-place upgrade change the home folder or server folders.

The Windows Service is split across multiple folders to make upgrading easy and low risk.

  • Install Location: By default, the install location for Octopus on Windows is C:\Program Files\Octopus Deploy\Octopus. The install location contains the binaries for Octopus Deploy and is updated by the MSI.
  • SQL Server Database: Since Octopus Deploy 3.x, the back-end database has been SQL Server. Each update can contain 0 to N database scripts embedded in a .dll in the install location. The Octopus Manager invokes those database scripts automatically.
  • Home Folder: The home folder stores configuration, logs, and other items unique to your instance. The home folder is separate from the install location to make it easier to upgrade, downgrade, uninstall/reinstall without affecting your instance. The default location of the home folder is C:\Octopus. Except in rare cases, this folder is left unchanged by the upgrade process.
  • Instance Information: The Octopus Deploy Manager allows you to configure 1 to N instances per Windows Server. The Octopus Manager stores a list of all the instances in the C:\ProgramData\Octopus\OctopusServer\Instances folder. Except in rare cases, this folder is left unchanged by the upgrade process.
  • Server Folders: Logs, artifacts, and packages are too big for Octopus Deploy to store in a SQL Server database. The server folders are subfolders in C:\Octopus\. Except in rare cases, these folders are left unchanged by an upgrade.
  • Tentacles: Octopus Deploy connects to deployment targets via the Tentacle service. Each version of Octopus Deploy includes a specific Tentacle version. Tentacle upgrades do not occur until after the Octopus Deploy server is upgraded. Tentacle upgrades are optional; any Tentacle greater than 4.x will work with any modern version of Octopus Deploy. We recommend you upgrade them to get the latest bug fixes and security patches when convenient.
  • Calamari: The Tentacles facilitate communication between Octopus Deploy and the deployment targets. Calamari is the software that does the actual deployments. Calamari and Octopus Deploy are coupled together. Calamari is upgraded automatically during the first deployment to a target.components.

Install the newer version of Octopus Deploy

Installing a newer version of Octopus Deploy is as simple as running MSI and following the wizard. The MSI will copy all the binaries to the install location. Once the MSI is complete, it will automatically launch the Octopus Manager.

Validation Checks

Octopus Deploy will perform validation checks before upgrading the database. These validation checks include (but are not limited to):

  • Verify the current license will work with the upgraded version.
  • Verify the current version of SQL Server is supported.

If the validation checks fail, don't worry, install the previously installed version of Octopus Deploy, and you will be back up and running quickly.

Database Upgrades

Each release of Octopus Deploy contains 0 to N database scripts to upgrade the database. The scripts are run in a transaction; when an error occurs, the transaction is rolled back. If a rollback does happen, gather the logs and send them to support@octopus.com for troubleshooting. You can install the previous version to get your CI/CD pipeline back up and running.

Testing the upgraded instance

It is up to you to decide on the level of testing you wish to perform on your upgraded instance. At a bare minimum, you should:

  • Do test deployments on projects representative of your instance. For example, if you have IIS deployments, do some IIS deployments. If you have Java deployments, do some Java deployments.
  • Check previous deployments, ensure all the logs and artifacts appear.
  • Ensure all the project and tenant images appear.
  • Run any custom API scripts to ensure they still work.
  • Verify a handful of users can log in, and that their permissions are similar to before.
  • Build server integration; ensure all existing build servers can push to the upgraded server.

We do our best to ensure backward compatibility, but it impossible to cover every user scenario for every possible configuration. If something isn't working, please capture all relevant screenshots and logs and send them over to support@octopus.com for further investigation.

Maintenance Mode

Maintenance mode prevents non-Octopus Administrators from doing deployments or making changes. To enable maintenance mode go to Configuration ➜ Maintenance and click the button Enable Maintenance Mode. To disable maintenance mode, go back to the same page and click on Disable Maintenance Mode.

Backup the SQL Server database

Always back up the database before upgrading Octopus Deploy. The most straightforward backup possible is a full database backup. Execute the below T-SQL command to save a backup to a NAS or file share.

BACKUP DATABASE [OctopusDeploy]
          TO DISK = '\\SomeServer\SomeDrive\OctopusDeploy.bak'
             WITH FORMAT;

The BACKUP DATABASE T-SQL command has dozens of various options. Please refer to Microsoft's Documentation or consult a DBA as to which options you should use.

Backup the server folders

The server folders store large binary data outside of the database. By default, the location is C:\Octopus. If you have High Availability configured, they will likely be stored on a NAS or some other file share.

  • Packages: The default location is C:\Octopus\Packages\. It stores all the packages in the internal feed.
  • Artifacts: The default location is C:\Octopus\Artifacts. It stores all the artifacts collected during a deployment along with project images.
  • Tasklogs: The default location is C:\Octopus\Tasklogs. It stores all the deployment logs.

Any standard file-backup tool will work, even RoboCopy. Very rarely will an upgrade change these folders. The release notes will indicate if these folders are going to be modified.

In-place upgrade of the main instance

Upgrading your main Octopus Deploy instance should follow the same steps you did with the test or cloned instance. Don't forget to run your backups!

Upgrade High Availability

In general, upgrading a high available instance of Octopus Deploy follows the same steps as a typical in-place upgrade. Download the latest MSI and install that. The key difference is to upgrade only one node first, as this will upgrade the database, then upgrade all the remaining nodes.

Attempting to upgrade all nodes at the same time will most likely lead to deadlocks in the database.

The process should look something like this:

  1. Download the latest version of Octopus Deploy.
  2. Enable maintenance mode.
  3. Stop all the nodes.
  4. Backup the database.
  5. Select one node to upgrade, wait until finished.
  6. Upgrade all remaining nodes.
  7. Start all remaining stopped nodes.
  8. Test upgraded instance.
  9. Disable maintenance mode.

A small outage window will occur when upgrading a highly available Octopus Deploy instance. The outage window will happen between when you shut down all the nodes and upgrade the first node. The window duration depends on the number of database changes, the size of the database, and compute resources. It is highly recommended to automate your upgrade process to reduce that outage window.

Rollback failed upgrade

While unlikely, an upgrade may fail. It could fail on a database upgrade script, SQL Server version is no longer supported, license check validation, or plain old bad luck. Depending on what failed, you have a decision to make. If the cloned instance upgrade failed, it might make sense to start all over again. Or, it might make sense to roll back to a previous version. In either case, if you decide to roll back, the process will be:

  1. Restore the database backup.
  2. Restore the folders.
  3. Download and install the previously installed version of Octopus Deploy.
  4. Do some sanity checks.
  5. If maintenance mode is enabled, disable it.

Restore Backup of database

Use SQL Server Management Studio's (SSMS) built-in restore backup functionality. SSMS provides a wizard to make this process as pain-free as possible. Be sure to consult a DBA or read up on Microsoft's Documentation.

Restore Octopus Folders

Octopus Deploy expects the artifacts, packages, and tasklog folders to be in a specific format. The best chance of success is to:

  1. Copy the existing folders to a safe location.
  2. Delete the contents of the existing folders.
  3. Copy the contents of the existing folders from the backup.
  4. Once the rollback is complete, delete the copy from the first step.

Find and download the previous version of Octopus Deploy

Octopus Deploy stores the installation history in the database. Run this query on your Octopus Deploy database if unsure as to which version to download:

SELECT TOP 5 [Version]
  FROM [dbo].[OctopusServerInstallationHistory]
  ORDER BY Installed desc

When you know the version to install, go to the previous downloads page.

Installing the previous version

The key configuration items, such as connection string, files, instance information, etc., are not stored in the install directory of Octopus Deploy. To install the previous version, first, uninstall Octopus Deploy. Uninstalling will only delete items from the install directory, or C:\Program Files\Octopus Deploy\Octopus. Then run the MSI to install the previous version.

Additional items to note

Earlier versions of 3.x, including 3.1, 3.4, and 3.5, also carry some additional caveats to make a note of. Before upgrading to a modern version of Octopus Deploy, please keep these in mind.

Upgrading to Octopus 3.1 or greater

Summary: Tentacle was upgraded from .NET 4.0 to .NET 4.5 to enable TLS 1.2.

You can upgrade to Octopus Server 3.1 without upgrading any Tentacles and get all of the new 3.1 deployment features because Calamari will continue to work on both Tentacle 3.0 and 3.1.

This is the first modern version of Octopus Server where there has been a Tentacle upgrade, and it has caused some confusion. This section aims to answer some of the most commonly asked questions about upgrading to Octopus 3.1 and the impact on Tentacles.

Am I required to upgrade to Tentacle 3.1? No, you aren't required to upgrade to Tentacle 3.1. Tentacle 3.0 will still work and benefit from Calamari's latest version and all of the deployment features we shipped in Octopus 3.1.

What changed with Tentacle 3.1? The Octopus-Tentacle communication protocol in 3.1 can use TLS 1.2, which requires .NET 4.5 to be installed on the server.

When should I upgrade to Tentacle 3.1? We recommend upgrading to Tentacle 3.1 as soon as you are able. Upgrading Tentacles in Octopus 3.1 is automated and can be done through the Environments page. The main benefit you'll get is the Octopus-Tentacle communication protocol can use TLS 1.2.

What would stop me from upgrading to Tentacle 3.1? Your server needs to support .NET 4.5. Tentacle 3.1 requires .NET 4.5 to be installed on the server, which is what enables TLS 1.2 support, and .NET 4.5 is supported on Windows Server 2008 SP2 or newer. This means Windows Server 2003 and Windows Server 2008 SP1 are not supported for Octopus Server or Tentacle 3.1.

How can I make Octopus/Tentacle use TLS 1.2 instead of TLS 1.0? Octopus Server and Tentacle to 3.1 will use TLS 1.2 by default. Tentacle 3.0 will still work with Octopus 3.1, but the communication protocol will fall back to the lowest-common-denominator of TLS 1.0.

Can I have a mixture of Tentacle 3.0 and 3.1? I'm not ready to upgrade some of my application servers. Yes, you can have a mixture of Tentacle 3.0 and 3.1 working happily with Octopus 3.1. We have committed to maintaining compatibility with the communication protocol.

If I keep running Tentacle 3.0 does that mean I won't get any of the new Octopus 3.1 deployment features? The deployment features are handled by Calamari and Octopus Server makes sure all Tentacles have the latest Calamari. This means servers hosting Tentacle 3.0 or 3.1 will get all of the new deployment features we shipped with Octopus 3.1 by means of the latest Calamari.

Will you continue to support Windows Server 2003 or Windows Server 2008 SP1? No, from Octopus 3.1 onward, we are dropping official support for Octopus Server and Tentacle hosted on Windows Server 2003 or Windows Server 2008 SP1.

Tentacle communications protocol
Read more about the Octopus - Tentacle communication protocol and Troubleshooting Schannel and TLS.

Upgrading to Octopus 3.4 or greater

See the Release Notes for breaking changes and more information.

Using TeamCity NuGet feeds? You will need to upgrade your TeamCity server to v9.0 or newer and enable the NuGet v2 API. Octopus 3.4+ no longer supports the custom NuGet v1 feeds from TeamCity 7.x-8.x. We recommend upgrading to the latest TeamCity version available due to continual improvements in their NuGet feed - or switch to using the Octopus built-in repository.

Want to use SemVer 2 for packages or releases? You will need to upgrade OctoPack and/or Octopus CLI to 3.4 or newer.

Upgrading to Octopus 3.5 or greater

Some server configuration values are moved from the config file into the database in 3.5+.

If you are upgrading to a 3.5+ version, please backup your server config file prior to upgrading. If you need to downgrade, then replace the config with the original file after the downgrade and restart the Octopus Server.

Troubleshooting

In a few cases, a bug in a 3rd party component causes the installer to display a "Installation directory must be on a local hard drive" error. If this occurs, running the install again from an elevated command prompt using the following command (replacing Octopus.3.3.4-x64.msi with the name of the installer you are using):

msiexec /i Octopus.3.3.4-x64.msi WIXUI_DONTVALIDATEPATH="1"

Need support? We're here to help.