how to deploy backend

After our bootcamp was done, we were instructed to create a portfolio website and given my interests in both frontend (my creative side) and backend (my curiosity for more of the technical engine that drives a site)- I decided to make my site fullstack. For example, I wanted to host my data tables for my bootcamp scores and feedback and projects on the backend.

When researching the how-to, I noticed a lack of resources for deploying a fullstack site and specifically for how to deploy the backend.

I wanted to create a resource to share my learnings on how to deploy the backend with the hope that this can help others. To preface, yes- there can be multiple approaches, but this here is specifically the approach my mentor and I took to deploy the backend. Please also note- that yes Heroku does require a card (~ $5, $9/ month), so if you want to avoid the billing - you can also just hardcode your backend data on the frontend. :)

To start off - we used Heroku to deploy and locally- we used Postgres to store the data. It is a very beginner-friendly site compared to some of the other more complex sites like AWS. In the steps below, we will go over:

• Account Set Up
• Postgres Set Up
• Migrating Data
• Connecting to Frontend

Before reading these steps, please note that the terminal commands are specific to Mac. As deployment strategies can vary based on your versions, below are the specific versions of systems I had:

• React: 18.2.0
• Spring: 3.3.0
• Postgres: 14.12

Another optional thing to note if it makes it easier for you to organize the work, you will want to have a separate repo on Github respectively for both the frontend and backend.

Account Set Up

1. To start, you can go to heroku.com to sign up.

2. Click Create New App or navigate to:

https://dashboard.heroku.com/apps

3. Give your app a name.

4. From your Dashboard (https://dashboard.heroku.com/apps), click on the app name.

5. Add a system.properties file to your backend Java project.

Note: please keep the page open from step 4. This step 5 is done on your IDE to ensure proper deployment.
You will add this system.properties file to the root of your backend Java project directory. In this file, add the following:
Make sure you replace the 21 with your actual version number of Java.

java.runtime.version=21

This file helps Heroku understand which version of Java to use when running your application. Without it, Heroku might default to a version that is not compatible with your application, leading to potential runtime issues.

6. Click on deploy and click Connect to Github.

After connecting your GitHub repository, you'll see options to set up automatic deployments. Choose the GitHub branch you want Heroku to deploy automatically from (usually main or master). Optionally, enable automatic deploys so that every time you push to the chosen branch on GitHub, Heroku will automatically deploy those changes.

If you are having issues with automatic deployment, you may manually deploy. You will see that option at the bottom of the Deploy page.

After successful deployment, Heroku assigns a URL to your application. You can find this URL either in the output of the deployment process or by logging into your Heroku account and navigating to your app's dashboard. Make sure you write that URL down in a secure spot, as this will be the updated endpoint for your API calls.

Once you have obtained the URL (i.e. https://your-app-name.herokuapp.com), you can use it to make HTTP requests to your backend API endpoints deployed on Heroku. Replace your-app-name with the actual name of your Heroku app.

For example, if your backend API endpoint is /api/data, your complete URL for making requests would be https://your-app-name.herokuapp.com/api/data.

7. Check the logs to verify the correct Java version is being used.

Logs for both successful and unsuccessful builds are available from your app’s Activity tab in the Heroku Dashboard. You may read more steps for this under Heroku Logs documentation here.

After deploying, you should also double check the Heroku deployment logs to ensure the correct Java version is being used:

• Go to the Heroku dashboard, select your app, and navigate to the "More" dropdown in the top-right corner. Choose "View Logs."
• In the logs, look for lines that mention the Java runtime version. This will help you confirm that the correct version is being used.
• If the version is incorrect, update the system.properties file with the correct version number and redeploy.

Postgres Set Up

Now let’s say you want to connect your existing Postgres database, i.e. say you are using Spring Boot and in the front end, you make the API call to the endpoints to get your data to display.

1. Click on the dots at top right next to your profile picture, and select Data.

2. Click Create one under Heroku Postgres and click on install.

3. Select the plan so you can host your database on Heroku.

The ones recommended for small-scale projects like a portfolio are Essential 0 ($5/month) or Essential 1 ($9/month). I got the latter.

Migrating Data

Now that the postgres instance is set up, now we can migrate our data from our local postgres to Heroku remote. An analogy is when we push code from local to your remote github repo, except in this case we are “pushing” our data.

1. First, you will want to install Docker.

Docker allows you to package an application along with its dependencies and configuration settings into a single, portable unit called a container. This makes it easier to develop and deploy applications. For example, when you use Docker to run PostgreSQL commands like pg_dump (to back up a database) or pg_restore (to restore a database), these commands execute within this isolated environment.

In our case, using Docker resolved a version conflict issue where Heroku server version of Postgres was 16.2 (and you can see that version here), but the pg_dump version was 14.12

You may type the command below on your terminal

brew install docker

… or if your terminal is being cranky and doesn’t want to work, then you can go to the Docker website and download Docker Desktop for Mac. Once installed, open the “Docker Desktop” application, skip through the various prompts until the docker daemon is running. Then you can close the docker desktop window and proceed to run docker commands in your shell session.

2. Then, you have to use pg_dump to create a create a backup file (*.dump) of your database for migration. You can run this command within Docker.

Type in your terminal the following:
You may see some abbreviated letters like -h and -U, etc. Here’s what they stand for and make sure to replace the word following the abbreviated letter for the following:

• -h is the host name, so if you are not locally using localhost, replace it with your host.
• -U is your local postgres username.
• -d is the name of your local postgres database.
• -f ashley-portfolio.dump: Specifies the filename (ashley-portfolio.dump) to save the dump.

docker run postgres:16 pg_dump -Fc --no-acl --no-owner -h localhost -U postgres -d ashley-portfolio-database -f ashley-portfolio.dump

Notice above we put postgres:16 so that it will match the server version of Heroku.
Note also: If you do not change directories (cd) before running pg_dump, the dump file will typically be saved in your home directory (~/) or wherever your terminal session is currently located.

Some more details if you are curious on the how and why behind this: pg_dump allows you to create a snapshot (backup) of your local PostgreSQL database (ashley-portfolio-database). This backup is crucial for preserving your data before transferring it to Heroku.

The backup file created by pg_dump (ashley-portfolio.dump) contains a consistent snapshot of your database, including the SQL commands necessary to remake the table structure. This file can then be transferred and restored into a different PostgreSQL database environment, such as one hosted on Heroku.

3. Upload your database pg_dump backup file to Heroku:

Now that you have created a backup of your local PostgreSQL database using pg_dump, the next step is to migrate this data to your PostgreSQL database hosted on Heroku.

Use pg_restore to upload your local database backup (ashley-portfolio.dump) to your Heroku PostgreSQL database:

docker run -e PGPASSWORD=yourHerokuDatabasePassword -v /path/to/your/backup:/my-portfolio-backup postgres:16 pg_restore -h herokuHostName -p 5432 -U yourHerokuUsername -d yourHerokuDatabaseName /my-portfolio-backup

Replace /path/to/your/backup, yourHerokuDatabasePassword, herokuHostName, 5432, the postgres version:16, yourHerokuUsername, yourHerokuDatabaseName with your actual paths and database details.

You can find this information by clicking the 9 dots at the top right of your Heroku page next to your profile picture. Click on Data. From there, it will open a page and you will see Datastores. Click on your datastore. Then you will see another page open, and at the top bar, it will say Overview, Durability, Settings. Make sure you select Settings. From there, click on View Database Credentials. Make sure that you don’t write this information down in an insecure environment.

Here is an explanation of what that Docker command means:

• docker run: This command starts a new Docker container.
• -e PGPASSWORD=yourHerokuDatabasePassword: This sets an environment variable inside the container. Here, PGPASSWORD is being set to your Heroku database password. Environment variables are a way to pass configuration settings to your application.
• -v /path/to/your/backup:/my-portfolio-backup: This option links a directory on your host machine (your computer) to a directory inside the container. The part before the colon (/path/to/your/backup) is the path on your host machine where your backup file is stored. The part after the colon (/my-portfolio-backup) is the path inside the container where the backup file will be accessible.
• postgres:16: This specifies the Docker image to use, in this case, version 16 of the PostgreSQL image. This ensures compatibility and forces the container to run with PostgreSQL version 16.
• pg_restore: This is the command that will run inside the container. It restores a PostgreSQL database from a backup file.
• -h herokuHostName: This specifies the host name of your Heroku PostgreSQL database.
• -p 5432:This specifies the port number to connect to. The default port for PostgreSQL is 5432.
• -U yourHerokuUsername: This specifies the username to connect to the PostgreSQL database on Heroku.
• -d yourHerokuDatabaseName: This specifies the name of the PostgreSQL database to restore the backup into.
• /my-portfolio-backup: This is the path to the backup file inside the container. It should match the directory we mounted earlier.

4. The last step is to have the migrated database appear on your local Postgres (this way if you need to view the data, or make updates- you can do so).

Using the aforementioned steps from step 3 on how to view your database Heroku credentials, make sure you keep that page open.
Open Postgres from your desktop. Right click on Servers in Postgres and then click Register and select Server.
From there, in the popup, select Connections and type in the info from your Heroku database credentials.

Now, when you open up Postgres, you should see a server called heroku. When you expand it, you will see databases. You can search for the one that matches the database name in your Heroku database credentials. Once you expand the database, click on Schemas to expand. Then, click on public to expand and then from there click on Tables to expand. Now, you can go to each table and run queries.

Connecting to Frontend

1. To set up the frontend you can deploy your frontend repo on Github on Netlify via these steps found in Netlify documentation.
2. You will want to make sure that for any API calls you make on the frontend code, that the API URL is updated from localhost to the new URL (i.e. https://your-app-name.herokuapp.com) and you may refer Account Setup Step 5 for a refresher on that. :)
3. After you finish deploying on Netlify, then you will get a link to your website which you can visit to visually see your fullstack site.