The cloud platform [Heroku](https://www.heroku.com/home) provides "Free & Hobby" plan (non-commerical, PoC's, MVP's, personal projects) for deploying apps. This document describes how to deploy a GEARS generated application to Heroku. If you like some more details you can go to https://devcenter.heroku.com/categories/working-with-spring-boot to find our more about deploying spring-boot applications, how to scale them and how to make them production ready.
-[1. Prerequisites](#1-prerequisites)
-[2. Deploy your app](#2-deploy-your-app)
-[3. Deploy DB and connect to it](#3-deploy-db-and-connect-to-it)
-[4. Use runner to load data and run scenarios](#4-use-runner-to-load-data-and-run-scenarios)
-[5. Remove/Destroy a Heroku application](#5-removedestroy-a-heroku-application)
# 1. Prerequisites
- All GEARS prerequisites as described in [[Home]].
- A GEARS generated and built application that you tested locally so you know it should work. We'll use [order_products](https://gitlab.com/xlrit/demo_cases/order_products) as an example application.
- A Heroku account which you can get from https://www.heroku.com/
- The [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli#download-and-install) downloaded and installed.
# 2. Deploy your app
1. Create a file called `Procfile` in your application folder with the following content:
2. Create a file called `system.properties` with the following content:
```properties
java.runtime.version=11
```
3. Execute the following commands in a terminal. We will assume a Windows CMD terminal:
| command | explanation |
| :-- | :-- |
| `set HEROKU_APP=order-products` | set name of Heroku app. </br>**Beware that:** app names must be unique. So perhaps you should use a different name because this one may already be taken. |
| `heroku login` | Login to Heroku |
| `heroku create --no-remote` | Create Heroku app without building it in cloud |
| `heroku deploy:jar target/order_products/target/order_products.jar` | Deploy executable jar |
| `heroku logs --tail` | See log of your app starting |
If the log gives no error and says `Started OrderProductsApplication in 35.921 seconds` your app has been deployed and has started. You can verify by the command:
```cmd
heroku open
```
This will launch you default browser and open the URL to your app.
# 3. Deploy DB and connect to it
By default the app will use an in-memory database. This means any time the app is restarted the database will also be lost. This chapter describes how to create a persistent Postgres database and attach it to your app.
1. From a terminal (assuming CMD) execute command: `heroku addons:create heroku-postgresql`. _This is enough to create Postgres DB. The app will also be restarted and attached to this new DB_.
2. Execute command: `heroku config`. _This will show DATABASE_URL. It will contain all info to connect to the DB. The format is_ `DATABASE_URL: postgres://<username>:<password>@<host>:<Port>/<DB name>`.
3. Download and install [Dbeaver](https://dbeaver.io/download/) _which is a lightweight Database manager (and apparently better than pgAdmin).
4. From DBeaver menu **Database > New Database Connection**. Choose **Postgres > Next**.
5. If you do not yet have Postgres drivers, you are presented with the option to download them. Please do so.
6. Next enter the info to connect to the DB and click **Finish**.
You can now browse the database by expanding the objects in the Database Navigator (left part of the screen). For instance expand **Databases > Schemas > public > Tables**. You can now r-click on one of the tables and choose **View Data**. It should look like this:
.
DBeaver also has a nice ERD viewer that may be helpfull. You can access it with tab **ERD Diagram**. It looks like this:
You can now also run all sort of SQL scripts by clicking the **SQL** button and copy pasting in SQL scripts. If you do not have the scenarion runner available, this would also be a good way to load the data in that is often in the form om some sql script files in the **data** folder of a typical GEARS project.
Note that by default those SQL scripts use the H2 SQL dialect. This means you may need to adjust your scripts a but to match it with Postgres. See the notes on the end of the next chapter about that.
# 4. Use runner to load data and run scenarios
It is possible to load data an run scenarios on your deployed app. This is how you do it:
1. Open the application in your browser.
2. Download the certificate from the browser (as described [here](https://medium.com/@menakajain/export-download-ssl-certificate-from-server-site-url-bcfc41ea46a2)) as a "DER encoded binary X.509 (.CER)", e.g. to `C:\Windows\Temp\herokuapp.cer`
3. Open CMD as Administrator.
4. Execute command: `keytool -cacerts -importcert -file C:\Windows\Temp\herokuapp.cer -alias herokuapp` (the default password is **changeit**)
5. You may get an error saying `alias <herokuapp> already exists`. If so remove it with command: `keytool -cacerts -delete -alias herokuapp`.
6. From your VS Code GEARS project add a the following setting in the `.vscode\settings.json` file: `"gears.runner.endpoint": "https://order-products.herokuapp.com/graphql"`
7. From VS code press **CTRL+B** and choose **GEARS:...Load data**.
8. From VS code press **CTRL+B** and choose **GEARS:...Run scenarios**.
**Note that:** Postgres has different attribute types versus H2 DB's. For instance boolean values are actually `true` and `false` in Postgres but are `1` and `0` in H2. The SQL should match these differences.
# 5. Remove/Destroy a Heroku application
Removing (in other words completely destroying) an Heroku application is done with the following command:
heroku apps:destroy
This will remove both the (current) application as well as its attached database.
