Octopus Deploy Documentation

Creating a test instance

Last updated

There is always a risk an in-place upgrade will fail. The risk increases as more versions have been released between upgrades. We do our best to test many different configurations to put downward pressure on that risk. However, we can't cover every hyper-specific scenario. Also, there might be a new feature, or a breaking change introduced. Creating a test instance will help you reduce the risk for you and your company.

Overview

There are two approaches to creating a test instance:

  1. Subset of projects representing the main instance.
  2. Clone of the main instance.

Test instance with a subset of projects

Setting up a test instance with a subset of projects over a full clone has several advantages.

  • It is much easier to set up and configure than a clone. It is also easy to automate the setting up and tearing down a test instance on demand.
  • There is tooling in place to export specific projects.
  • A clone does a full clone of everything, including deployment targets and triggers, increasing the risk of having the sandbox instance connect to production when the instance initially starts up. You will need to disable all the targets to prevent this from happening.
  • A clone might have hidden configuration options, such as server folders, that you have to change.

The disadvantage of a subset of projects over a full clone is that there could be significant drift between projects, and you might miss something.

The process to create an instance with a subset of projects is:

  1. Download the same version of Octopus Deploy as your main instance.
  2. Install Octopus Deploy on a new VM.
  3. Export a subset of projects from the main instance.
  4. Import that subset of projects to the test instance.
  5. Test and verify the test instance.

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.

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

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.

Test instance is a clone

Setting up a test instance as a clone of the main instance has a few advantages over a subset of projects.

  • Upgrades are much closer to a one to one comparison.
  • You can do a full test of all integrations with Octopus Deploy.

Configuring a clone typically takes much more time and compute resources. There are backup locations to consider, targets to disable, and more.

Creating a clone of an existing instance involves:

  1. Enabling maintenance mode on the main instance.
  2. Backing up the database of the main instance.
  3. Disabling maintenance mode on the main instance.
  4. Restoring the backup of the main instance's database as a new database on the desired SQL Server.
  5. Downloading the same version of Octopus Deploy as your main instance.
  6. Installing that version on a new server and configuring it to point to the cloned database.
  7. Copying all the files from the backed up folders from the source instance.
  8. Optionally, disabling targets on the cloned instance.

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.

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.

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

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.

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.

Need support? We're here to help.