Rolling back an NGINX deployment

NGINX is a popular web server for Linux deployments. This guide will cover how to roll back a Node.js application accessed through NGINX. In this example, NGINX is a reverse proxy to a Node.js service running as a systemd service. The application has two components:

  • Database
  • Website

Rolling back the database is out of scope for this guide. This article describes reasons and scenarios in which rolling back a database could result in data loss or incorrect data. This guide assumes that there are no database changes or the changes are backward compatible. Because the database changes are out of scope for rollbacks, the database package will be skipped during the rollback process.

While this guide is for Node.js, the same process can be used for any framework, language or platform NGINX supports.

Existing deployment process

The existing deployment process is:

  1. Deploy to MongoDB.
  2. Deploy to NGINX.
  3. Verify Application.
  4. Notify Stakeholders.

Original deployment process for Node.js application

View the deployment process on our samples instance. Please login as a guest.

Zero-configuration rollback

The easiest way to rollback to a previous version is to:

  1. Find the release you want to roll back.
  2. Click the REDEPLOY button next to the environment you want to roll back.

That redeployment will work because a snapshot is taken when you create a release. The snapshot includes:

  • Deployment Process
  • Project Variables
  • Referenced Library Variables Sets
  • Package Versions

Re-deploying the previous release will re-run the deployment process as it existed when that release was created. By default, the deploy package steps (such as deploy to IIS or deploy a Windows Service) will extract to a new folder each time a deployment is run, perform the configuration transforms, and run any scripts embedded in the package.

Zero Configuration Rollbacks should work for most our customers. However, your deployment process might need a bit more fine tuning. The rest of this guide is focused on disabling specific steps during a rollback process.

Rollback process

For most rollbacks, the typical strategy is to skip the database step while re-deploying the Node.js application website. In addition, a rollback indicates something is wrong with a release, so we’d want to prevent that release from progressing.

The updated deployment process will be:

  1. Calculate Deployment Mode
  2. Deploy to MongoDB (skip during rollback)
  3. Deploy to NGINX
  4. Block Release Progression
  5. Verify the Application
  6. Notify stakeholders

simple rollback for windows deployment

View the deployment process on our samples instance. Please login as a guest.

calculate deployment mode

Calculate Deployment Mode is a community step template created by Octopus Deploy. It compares the release number being deployed with the current release number for the environment. When the release number is greater than the current release number, it is a deployment. When it is less, then it is a rollback. The step templates sets a number of output variables, including ones you can use in variable run conditions.

Skip database deployment step

The database deployment step should be skipped during a rollback. Unlike code, databases cannot easily be rolled back without risking data loss. For most rollbacks, you won’t have database changes. However, a rollback could accidentally be triggered with a database change. For example, rolling back a change in Test to unblock the QA team. Skipping these steps during the rollback reduces the chance of accidental data loss.

To skip these steps during a rollback, set the variable run condition to be:

#{Octopus.Action[Calculate Deployment Mode].Output.RunOnDeploy}

We also recommend adding or updating the notes field to indicate it will only run on deployments.

windows updating notes field

Block release progression

Blocking Release Progression is an optional step to add to your rollback process. The Block Release Progression step template uses the API to prevent the rolled back release from progressing.

This step includes the following parameters:

  • Octopus Url: #{Octopus.Web.BaseUrl} (default value)
  • Octopus API Key: API Key with permissions to block releases
  • Release Id to Block: #{Octopus.Release.CurrentForEnvironment.Id} (default value)
  • Reason: This can be pulled from a manual intervention step or set to Rolling back to #{Octopus.Release.Number}

This step will only run on a rollback; set the run condition for this step to:

#{Octopus.Action[Calculate Deployment Mode].Output.RunOnRollback}

To unblock that release, go to the release page and click the UNBLOCK button.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, October 4, 2023