Upgrading to the Latest Stack

Last updated 03 October 2019

This article describes how to upgrade your app to use the latest Heroku stack. What is a stack?

The Cedar-14 stack is end-of-life. Please follow the steps in this article to upgrade to a supported stack as soon as possible.

Testing your app on a new stack

Use one of the following methods to ensure your app works as expected on a new stack before upgrading.

If your organization uses review apps, we recommend testing a new stack by creating a new pull request. Simply define your stack in app.json:

{
   "stack": "heroku-18"
}

If you are running an app that requires the JVM, but does not use the Java buildback (e.g., jython or a Java Bridge), be sure to set the JVM as your first buildpack:

{
  "buildpacks": [
    {
      "url": "heroku/jvm"
    },
    {
      "url": "heroku/ruby"
    }
  ]
}

Creating a new app from an existing app

You can test a stack by creating a new test app from an existing application. To create a new app, from an existing app, first change to your code directory then run heroku create with the following parameters:

$ cd <yourcodedirectory>
$ heroku create --remote heroku-18 --stack heroku-18 <your app name with heroku-18 appended>

This command will:

  • Create a new app: <your app name with heroku-18 appended>
  • Set up a new Heroku git repository: heroku-18
  • Set the stack image to the latest stack

Be sure to add any add-ons (with heroku addons:create --remote heroku-18) and config (with heroku config:set --remote heroku-18) to the app that’s required for your code to run.

Apps that use Java, but not the Java buildpack

If you are running an app that requires the JVM, but does not use the Java buildback (e.g., jython or a Java Bridge), be sure to set the JVM as your first buildpack:

$ heroku buildpacks:add --index 1 --remote heroku-18 heroku/jvm

Followed by any additional buildpacks you need, such as Ruby:

$ heroku buildpacks:add --remote heroku-18 heroku/ruby

View a list of official Heroku buildpacks.

Deploy your app

Deploying your new app will NOT affect your currently running app. Push the source to the new remote repository.

$ git push heroku-18 master
Counting objects: 67, done.
...
-----> Ruby app detected
-----> Compiling Ruby/Rack
...
$ heroku open --remote heroku-18

Once the app is deployed, you should verify that it is working correctly, and if not, make any required changes or open a support ticket with the stack name in the subject line.

Upgrading an app

To upgrade via the CLI, set the stack on the production app

$ heroku stack:set heroku-18 -a <app name>
stack set, next release on production-app will use heroku-18
Run `git push heroku master` to create a new release on heroku-18

This does not immediately change the stack of the app, but the next release created will be deployed on the latest. If you have no changes to your source pending release, you can create an empty commit with no changes to ensure a new build:

$ git commit --allow-empty -m "Upgrading to heroku-18"
[master 973c3f7] Upgrading to heroku-18

To create the new release, push to your production app:

$ git push heroku master

Your production app is now running on the latest stack, and you should verify that everything is working as expected.

Upgrading via Dashboard

To upgrade via the Heroku Dashboard, navigate to your app settings page. Click the Upgrade Stack button. Confirm that you want to upgrade, which will set the stack to the latest version. You will see that the stack upgrade is pending; the upgrade with take effect on the next deploy.

Rolling back

If your production app is not working after you changed the stack, you can revert back until you’ve contacted customer support, debugged and resolved the issue.

First you need the release version of the previous release:

$ heroku releases
=== production-app Releases
v13  Deploy 973c3f7                  joe@example.com   2014/07/09 10:55:16
v12  Deploy ddb317d                  jill@example.com  2014/07/07 10:46:26
...

Then rollback to a release that was running on the previous stack:

$ heroku rollback v12

Your production app is now running on the previous stack.

Locales

Starting with Heroku-16, locales are installed via buildpack. Create a .locales file at your app’s root, with all the locales you need. For example:

de_DE
fr_FR

and add the locales buildpack to your app:

$ heroku buildpacks:add https://github.com/heroku/heroku-buildpack-locale

After you’ve added the buildpack, you’ll need to redeploy your application.

For Java applications, support for locale-sensitive behavior in the java.util and java.text packages is almost entirely platform independent, so all locales are supported in the same way and simultaneously, independent of the host operating system and its localization. The only platform dependent functionality is the setting of the initial default locale and the initial default time zone based on the host operating system’s locale and time zone. Whether you need the locale buildpack for your Java app depends on what your application does.

3rd-party buildpacks

We expect most 3rd-party buildpacks will work with a new stack. If your app is using a 3rd-party buildpack, and you experience an issue building your app, we recommend clearing the buildpack cache:

$ heroku plugins:install heroku-repo
$ heroku repo:purge_cache

If clearing the buildpack cache doesn’t work, we suggest opening up an issue on the buildpack’s GitHub page.

Feedback

Log in to submit feedback.