heroku_guide_to_upgrade_to_new_stack.md

Testing with a newer stack on Heroku while keeping the existing app on the current stack

Heroku Official Guide

Manual testing (for heroku-24-stack) with a Ruby-on-Rails app

1. Create an app: heroku create --remote heroku-24 --stack heroku-24 <your app name>-heroku-24

   • creating an app: <your app name>-heroku-24; let us call it <your-app-24>

2. Associate the add-ons that are associated with your current one

3. Copy all config values to the heroku-24 app

   • heroku config --shell --remote heroku lists all config values of your existing app. Although they can be copy-pasted to the setting command, be careful about the quotes! You may end up including extra quotes in the values set.
   • Check out with heroku config --shell --remote heroku24

4. Foc CLI, you should add an option of either --remote heroku-24 or --app <your-app-24> to work on the new (test) stack. Some tasks accept both, but some do only --app.

   • Also, when you work on your existing stack, you now must specify --app (or --remote), while the new stack is alive.

5. Modify your app according to heroku-24

   • Make sure you are on main branch: git status; git branch
   • The branch must be main (!) (or master (?)) according to Heroku's policy.
   • Therefore, unless you prepare a dedicated separate development environment for the new stack, you basically must share the Git branch with your existing one. This means that you should avoid updating the existing app while tweaking your app for heroku-24; instead, you should do testing and migration to upgrade to the new stack in one go.
   • In the app code, you must at least change the database configuration (i.e., database name, user name, password) in your app (in particular, the DB password is not fixed on heroku and is taken from a dedicated environmenal variable), so you must edit the file for heroku-24). See the next item.

6. As for the database, you can view all the necessary parameters on your Dashboard on Heroku Dashboard.

   • For Rails, you simply copy & paste the database name, user name, and password on config/database.yml. Plain text is fine (but you may well use a pair of single quotations).
   • heroku pg:psql --remote heroku-24 may work straightaway.
     • Your Heroku Dashboard may provide a direct access CLI (I don't remember).
     • Alternatively, once you have pushed your app, as long as the build have been completed successfully and you have successfully created a DB (even if the app fails to start due to the lack of initial seeded data), you can run heroku db --app <your-app-24>; note that you are probably asked to type the DB password, which you can obtain from the dashboard.

7. Push Git to the new heroku-24 repository
   git push heroku-24 main

   • Here, the branch must be main
   • I'd recommend you to open heroku logs --app <your-app-24> --tail in a separate terminal before git-push so that you can get the full log while you are performing git push, partly because the app is unlikely to start before the initial migrations and seeding have been made, so a long series of backtrace for the error is likely. The full backtrace provides critical information for debugging of your app.
   • Check whether the build has been successful.

8. You may need more than one commit in the main branch of your Git repositories (both local and heroku-24)

   • This is fine, as long as you don't modify the exiting remote app.

9. Once the build has been succesful, run this to see if it launches successfully:
   heroku run --app <your-app-24> rails console

10. Upon success, make the db, migrate, and seed it:

    1. heroku run --app <your-app-24> db:create
    2. heroku run --app <your-app-24> db:migrate
       • Note that heroku run --app <your-app-24> db:migrate:status may not work at this stage! Still, db:migrate would succeed. 3 heroku run --app <your-app-24> db:migrate:status should now work, once the first migration has been made, even if the migrations process fails at a later stage.
    3. heroku run --app <your-app-24> db:seed
    4. Check the status with heroku run --app <your-app-24> rails console

11. Just in case, run heroku ps:restart --app <your-app-24>

12. Check at the website with heroku open --app <your-app-24>

    • The access URL should be listed on your dashboard on heroku

13. Once you have confirmed that your new app should work on the new stack heroku-24, remove your app from the test stack with

    • heroku apps:destroy --remote heroku-24

14. Suppose you have made some changes in the main brach of your local Git repository to make your app be accommodated in the new stack (which basically needs a fresh installing). Now you should backport the changes to your existing app (perhaps before migration to the new stack heroku-24)

    • A strategy is to commit the main branch without the temporary modification for the heroku-24 DB (in config/database.yml) and git rebase to delete the changed contents in config/database.yml. They will kind of remain only in the remote server of heroku-24, which is never a problem. In fact, those database parameters are all temporary, and so even if they are leaked, they won't be a security threat in practice. Still, it would be nice not to clatter your repository, be it local or different remote repository like Github.
    • In git rebase, specify the last commit number, which is pushed to your existing heroku repository.
    • For examlpe, suppose the commits are like:
      Ax - Bx - Cx (last-commit-to-push-to-existing) - Dx - Ex - Fx (pushed-to-heroku-24)
      Then, run git rebase -i Cx (NOTE: NOT Dx)
    • Don't forget to amend the date immediately: git commit --amend --no-edit --date=now
      Or this may work: git rebase --ignore-date HEAD
    • Check it with git log -n 15 --graph --decorate --pretty=oneline --abbrev-commit --all
    • git push heroku main
    • git status

15. Execute preparatory migration to heroku-24:

    • heroku stack:set heroku-24 -a $my_appname

16. Migration takes effect only after the first Git commit. Do it:

    • heroku maintenance:on -a $my_appname
    • git commit --allow-empty -m "Upgrading to heroku-24"
    • git push heroku main

17. Check if deployment is successful as usual (Notice no necessity of the app name):

    % heroku status
    % !her:0 ps
    % !her:0 logs --tail
     [^C]
    % !her:0 open
    % !her:0 maintenance:off -a $my_appname
    % !her:0 logs --tail
     [^C]
    % !her:0 run rails console