Heroku Deployment: A Walk Through for Beginners

12 min readAug 26, 2021

Heroku is a platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud. Sounds brilliant, and did I mention that it is also free?

So if you just want to deploy a basic app up into the cloud, then you’ve found your guide. This guide will walk through the CLI (command line interface) steps. This is for absolute beginners with a great deal of detail.

And to follow along at home, check out Heroku’s own excellent documentation: here

You may ask why Heroku? Benefits include:

1. Free

2. Works very will with Node & Express

3. Has an easy to use Postgres database add-on.

Bite-Size Steps to Deployment:

Making an account on Heroku
Checking the installation on your machine
Logging in to Heroku using the CLI ( first time & only time to do this )
Creating a place & name for the app in Heroku
Checking the created URL to ensure that it is there
Running the code on the app
Pushing the code up to the URL
Checking the app again — now deployed inside the URL we created
Users sign-in and JWT configuration
Seeding the database and user log in

Making an account on Heroku:

There are two ways to do it:

Using the desktop version of Heroku — I will not be doing it this way.
Command Line Interface: CLI

Check out the special CLI commands you need for this set up — look up https://devcenter.heroku.com/articles/heroku-cli

You will want to go to Heroku.com and set up an account. Keep track of your username and password, you’ll be using it shortly in step 3.

For Mac Users

Make sure you have brew installed. If you are yet to enjoy the wonders of brew, please check out brew here. I am using a Mac, so these instructions may not be idea for Linux/Windows users.

To install Heroku in the CLI, open your terminal type:

brew tap heroku/brew && brew install heroku

Non-Mac Users

See Other Installation Methods in the Heroku docs: here

Linux: https://snapcraft.io/

Windows: Find the button, it looks like this:

2. Checking your installation on your machine:

In the CLI or terminal type in:

heroku help

You should see a list of help options:

Please note! You only need to do this once, and only if you do not already have Heroku installed locally. If you see the long list of helpful Heroku text, then you have successfully installed.

3. Logging in to Heroku using the CLI ( first time & only time to do this )

In the CLI type in:

heroku auth

Then you will be prompted for your Heroku username & password — the one you used to sign up on their website.

You will only need to do this sign in once.

So from the above screen, you see the COMMANDS and line 2 is auth:login

That’s the one we need. So in the terminal type:

heroku auth:login

You will then see this: “Press any key to open up the browser to login or q…..”

It may not be so easy for everyone. I had an issue here. It was possibly personal to my environment — you may skip ahead if you do not have the same problem. Skip to the part about git remote -v.

For me, I pressed enter and a new tab opened up. Great, love it. And as has become par-for-the-course this tab had a warning about cookies….

I then scroll to the bottom of the page and see a large grey button “ Log In” to continue (despite the treacherous cookies).

I was given an error on this webpage:

However the CLI said I was logged in.

If you are successfully logged in your terminal will say:

Logging in… done
Logged in as <youremail@email.com> ← in green text

So….. I repeated the heroku auth:login entry in the CLI once more, (you may see two green text lines saying you are logged in now, I sure did).

And in the browser at this point I had moved past the warning about cookies. Instead I saw another well formatted page in purple with a more CSS-pretty button to Log-In on the website.

Clicked that again — and I am according to both the CLI & the browser safely logged in. Success!

Signed up on the Heroku website: YES!

Checked install: YES!

Logged into Heroku in the CLI using your Heroku username & password: YES!

See a green line of text with your email that says “Logged in as”: YES!

Steps 1–3 are complete! Great job, now we press on to the fun part.

Now, after steps 1–3 are complete it would be a good time to check what directory you are in. So in the terminal type in:

git remote -v

This tells you the version and more on Git can be found here

I personally needed to change directory (CLI command: cd ) into the directory which contains the app I am planning on deploying.

When you do, you should see something like this:

Side note : Now I will be switching to non-personal screen-shots going forward. This is to hide my email address for my own privacy.

That right there is the correct thing to see. We’re looking at the ssh key for the app I have resting in GitHub, waiting to be deployed. All good, but we need to create the application ON Heroku.

4. Creating a place & name for the app in Heroku

Create a place on Heroku for this app & give it a name. If you DON’T provide a name you will get a random string. No one wants to chase a random string for their app. So put in the app name, or something that makes sense.
But, the name you put in does not need to be the same as your current app name, it can be anything — but surely we would want the same/similar name, right?! Don’t confuse yourself.
Please note! This directly impacts the exact address of the hosted URL of the app — so choose wisely.

In the CLI type :

heroku create nameOfTheURL

nameOfTheURL is the name of the app. Do not add in .com or spaces, nothing but the name.

You see should something like this: the name here is fsa-boilerplate

Step 5. Checking the created URL to ensure that it is there

At this stage — you should be able to visit that url in the terminal. It will have a format similar to https://nameOfTheURL.herokuapp.com

In your browser copy/paste or type in that created URL you see in the terminal, and just like magic, you should see in the browser:

“Welcome to your new Heroku app”

But the rest is empty. There’s not much here. You have just make a place for the app to sit — you have not added in any of your beautiful app, yet.

Still This. Is. The. Link. you can send to people to view your app!

And like I said, your code is not running here yet! That is the next step!

6. Running the code on the app

So with the above Step 5: Heroku create nameOfTheURL

We have actually created a “ remote “ Which we can view in the usual git way:

So typing in the terminal:

git remote -v

Now, you should see something like this: where there are 4 total lines. 2 are the origin you know and love, and now 2 new ones which are Heroku.

So in order for us to get the code up onto this now newly created URL — all we have to do is push the code. Sounds too simple, I know! But it’s true.

For Step 7: There is an important check to make here.

MAKE SURE YOU ARE ON THE MAIN BRANCH TO DEPLOY

If you are in here looking at how to deploy your app, the main branch should be the most up to date branch. Branch organisation is another love of mine.

Non-main-branch-deployment messes up everything. It goes all weird. So merge your code, make the main branch the most up-to-date, get on that main branch. Now you’re ready to push your code to your new URL.

7. Pushing the code up to the URL:

Once you are sure you are on the hyper-up-to-date main branch, in the CLI type in:

git push heroku main

This will push up the code. Simple!
This also automatically do the usual things we manually do after pulling code down from GitHub:

Auto installs node, dependencies
Auto runs npm install
Auto installs package.json
Auto runs webpack
etc.

But wait — say it isn’t so:

Issues such as 5432 — not connecting to Postgres……

That is probably because WE are running the database — but by that logic, someone else with the URL will not be running that specific database. Makes sense, so let’s fix that now.

You will need to go into the code, so using VSCode or what ever code editing program you use go to your database file.

In the database.js file (usually of the database folder, inside server folder) look for the below code. Your file names will likely differ. But if you are lost just search for this key phrase: “ process.env.DATABASE_URL ” in your code editor.

Somewhere like: /server/database/database.js which will look something like this:

See the DATABASE_URL? In the above example at line 25.

We can use the line 25 to put a Postgres database on Heroku.

We are going to use an add-on to do this with Heroku. (By the way, this step can also be done on the website)

Back to the trusty terminal. Type in:

heroku addons

It should say you have no add-ons!!! Of course you don’t, you only just started with Heroku as a beginner. An add-on will be added now.

So in the CLI enter this exact line:

heroku addons:create heroku-postgresql:hobby-dev

This above CLI entry creates a Postgres add-on:

hobby : dev specifies it is a free version.

The database has been created!

Brilliant! The database is usable & functional. Trust me.

But this database is empty! Course it is, it’s not been seeded. Well, you have it seeded locally, I’m sure. But not this new-heroku-fabulous database. This new one is empty.

Separate from this unseeded question: you may have other questions. We created it… and it is apparently also database_URL… no other code changes in the code editor?! No nothing left to do but to seed this database…?

Why?

It’s because Heroku deliberately does this.

I am sorry that I do not have more reasons for it. It just is that way. But as engineers, I’m sure my word is not enough. Let’s check it.

Refresh the URL in the Heroku browser:

Looking at the Settings tab inside the Dashboard

You can see the Config Var area (scroll down to see this)

There is a Postgres string: this is the connection added as a variable for us. Magic! (see below screenshot)

8. Checking the app now deployed inside the URL we created

Refresh the app in the browser. ( the Heroku URL one )

It should look just like the app as it was before deployment, only now it’s on the url. Well done! But can we log-in? No, not with the usual authentication requirements. (For me it is JWT authentication)

9. Logging in & the errors with JWT, auth, etc

So if you have a log-in page as part of your app, now is the time to test this and set up authentication. Try to log-in as you would usually — on the log-in page or wherever you have it.

Error!?!?! Again! On the browser (URL) page?!

“ secretOfPrivateKey must have a value ”

Do not be alarmed. This error is a specific error and it is caused by JWT authentication which you have in your app.

So inside your VSCode or code editor, go into the package.json file, in the scripts object you will see:

“start-server”: “JWT=shh nodemon server: html, js, scs………….”

This above is the information we need to add this secret key to Heroku.

We are adding a secret key for JWT — a requirement that our app needs.

Because we don’t have it in Heroku yet. The app requires it to run on localhost, and therefore Heroku will need it too.

In the CLI we can set this up so that the authentication error is gone for good.

heroku config

After typing that in, in the terminal you should see something like this:

So, we see that we do have our DATABASE_URL, (seen above in green) But now we need to have a JWT one too.

It would be a good idea to get a list of commands for the terminal to do this.

To get a list of possible commands type in:

heroku config -h

This command gives you a list of possible commands in the CLI.

From this list you should see the “set” option. In the CLI type:

heroku config:set JWT=private-key

This will set the config variable.

Here private-key can be what ever you want to make it, just keep it consistent.

When you run “ heroku config” in the terminal again, you should then see the JWT you added. Like so:

This JWT key set up can also be done in the settings tab inside the dashboard of Heroku.

Try to sign-up again for your app in the browser and it should work for sign-up.

The log-in functionality requires your database, which we will seed now.

10. Seeding the database.

Our database is currently still unseeded on Heroku — in order to have users log-in you will need to access the database. So now we are connecting the database with Heroku.

So you will want to run the seed file you have listed inside the package.json. Your command in the package.json may vary.

So you’ll want to type into the terminal :

heroku run npm run seed

This above command is a little funny looking! It is not a typo. It is telling Heroku to run the command as per your usual seeding request via package.json.

As in: “Hey heroku, run this exact bit of code that I would usually type into my code editor terminal so I can seed the database.”