Skip to content

Quick Start Guide

Jump to bottom
Devon Hillard edited this page Sep 15, 2023 · 15 revisions

This is a Quick Start Guide to get you up and running with either the Embedded App setup, or the Standalone App approach.

This assumes you are starting with a local instance running for development. For production deployment and configuration please see the full documentation.

Embedded App Quick Start

Setup ngrok tunnel

Since you'll be running the application locally, and Shopify needs to be able to talk to the application's API, you need to make the application publicly accessible. The easiest way to do that is with a free utility called ngrok. It creates a secure network tunnel from a public facing hostname and IP address, back to your computer. It is free, although a paid account means you won't have to keep reconfiguring your application every time your ngrok hostname changes or have any limits on how long you can leave the tunnel up. Personally I use ngrok all the time and have found the Pro license to be well worth it. However, you can easily use the free version for this too.

  1. Sign up for your ngrok account

  2. Download and install the ngrok client. The instructions for install and connecting to your account are under Getting Started.

  3. Test ngrok. If you're using a free account, you will get a random hostname every time you create the tunnel, and can launch it like this:

ngrok http 8080

If it is able to connect, it will show you a domain name under Forwarding, which will look like:

https://XXXXXXX.ngrok.io -> http://localhost:8080

You will need this domain name, including the ngrok.io, for configuring your app later on. Keep in mind, this hostname will change every time you create the tunnel, so you will need to update the application configuration accordingly.

If you have a paid account you can go into your account on the ngrok.io website and under the Cloud Edge menu, you can find Domains. There you can create a New Domain. Something like myshopifyapptest.ngrok.io, or you can even setup your own custom root domain. Once that's created, you can use it like this:

ngrok http --subdomain=myshopifyapptest 8080

Create Shopify App in your Shopify Partner Account

  1. Create a Shopify Partner account (if you haven't already) - https://www.shopify.com/partners

  2. Create a new App (Custom or Public) in your Shopify Partner Admin Shopify App Creation Video Thumbnail

Instead of using the test.com URLs showing in the video above, use the following URLs:

App URL:

https://$YOUR-NGROK-HOSTNAME.ngrok.io/dash-embedded

Allowed redirection URL(s):

https://$YOUR-NGROK-HOSTNAME.ngrok.io/oauth2/authorization/shopify

https://$YOUR-NGROK-HOSTNAME.ngrok.io/login/oauth2/code/shopify

  1. Copy down the Shopify App Client Id and Client Secret shown at the end.

  2. Create a Development Storefront to test with. Go to the Stores option on the left nav, pick "Development store" as the type, and fill in the rest of the information as needed.

  3. Copy down the Development Store's URL, XXXXXX.myshopify.com

Get this project building locally

  1. Clone, fork, or download this project.

  2. Make sure you can build it, by going into the project directory and running grade build -xtest. If that doesn't complete successfully, figure out why and get it working.

Configure your local application

  1. Go to src/main/resources, and copy application-local-example.yml to application-local.yml

  2. Update this file with the Client ID, and Client Secret from the Shopify App you created in step 0 (as client-id and client-secret properties).

  3. Generate an AES encryption key. You can do this easily here - https://www.digitalsanctuary.com/aes-key-generator-free

  4. Put that key into the application-local.yml file under tokenEncryptionKey.

  5. Put your ngrok hostname under the shopify.app.hostname property, like this: https://xxxxxxx.ngrok.io

  6. Put your Development Store's hostname under the shopify.test.storeName property. This field does NOT have a leading http/https, just the hostname.

Setup your database

This will be used to store authorization information and your App's data. Out of the box the framework is configured to work with a MySQL/MariaDB database, already configured using JPA. The easiest way to handle this is with a Docker MariaDB container.

  1. Launch a MariaDB database instance as a Docker container:

docker run -p 127.0.0.1:3306:3306 --name shopify-test -e MARIADB_ROOT_PASSWORD=shopifytestroot -e MARIADB_DATABASE=shopifytest -e MARIADB_USER=shopifytest -e MARIADB_PASSWORD=shopifytest -d mariadb:latest

Run the application framework

Make sure your ngrok tunnel is still active, and your database (above) is running. Then you can launch the Spring Boot application.

  1. From the project directory run: gradle bootRun

It should run the Spring Boot application without any errors, and show:

Application availability state ReadinessState changed to ACCEPTING_TRAFFIC

If there are errors, work through them.

Test Installing the App to your Development Storefront

Clone this wiki locally