NONE: Simplify the project setup by using ngrok static domains (#48)

akostevich-atlassian · web-flow · commit 30e77a5135bc · 2023-11-20T12:55:41.000+11:00
diff --git a/.env.example b/.env.example
@@ -1,13 +1,30 @@
-# [AUTOFILLED] This URL is automatically filled
+# A URL of the app reachable by Jira.
+# For local development, consider using ngrok:
+# 1. Create an ngrok account: https://dashboard.ngrok.com
+# 2. Create your own static domain: https://dashboard.ngrok.com/cloud-edge/domains
+# 3. Use the created domain for `APP_URL` (e.g., https://foo-bar-baz.ngrok-free.app)
 APP_URL=
 
-# Auth Token for ngrok: https://dashboard.ngrok.com/get-started/setup
+###############################################################
+## The env variables below are required for development only ##
+###############################################################
+
+# These variables are needed for creating up an ngrok tunnel.
+# An ngrok auth token.
+# 1. Go to https://dashboard.ngrok.com/get-started/setup
+# 2. Find your ngrok auth token
 NGROK_AUTHTOKEN=
+# An ngrok static domain. This is the same domain used in `APP_URL` (e.g., `foo-bar-baz.ngrok-free.app`).
+# 1. Go to https://dashboard.ngrok.com/cloud-edge/domains or check the `APP_URL` value
+# 2. Find the created domain name
+NGROK_DOMAIN=
 
-# These variables are needed for the auto-app installation
-# Atlassian Jira URL eg. https://example-app.atlassian.net
+# These variables are needed for the app auto-installation.
+# An Atlassian site URL (e.g. https://example-app.atlassian.net)
 ATLASSIAN_URL=
-# Your Jira login email
+# Your Jira login email. You have to be the admin of a Jira instance.
 JIRA_ADMIN_EMAIL=
-# Create a new API token in Jira [https://id.atlassian.com/manage-profile/security/api-tokens]
+# An Atlassian API token.
+# 1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
+# 2. Create a new API token
 JIRA_ADMIN_API_TOKEN=
diff --git a/.eslintignore b/.eslintignore
@@ -1,4 +1,2 @@
 /**/*.js
-prestart.ts
-postinstall.ts
 playwright.config.ts
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -50,6 +50,7 @@ jobs:
         run: |
           echo "APP_URL=https://${{ secrets.NGROK_DOMAIN }}" > .env
           echo "NGROK_AUTHTOKEN=${{ secrets.NGROK_AUTHTOKEN }}" >> .env
+          echo "NGROK_DOMAIN=${{ secrets.NGROK_DOMAIN }}" >> .env
           echo "ATLASSIAN_URL=${{ secrets.E2E_ATLASSIAN_URL }}" >> .env
           echo "JIRA_ADMIN_EMAIL=${{ secrets.E2E_JIRA_ADMIN_USERNAME }}" >> .env
           echo "JIRA_ADMIN_API_TOKEN=${{ secrets.E2E_JIRA_ADMIN_PASSWORD }}" >> .env
diff --git a/README.md b/README.md
@@ -8,50 +8,56 @@ This app is aimed to help you to easily add your integration in Jira.
 - [Pre-requisites](#pre-requisites)
 - [Getting started](#getting-started)
 - [Manual Install](#manually-installing-the-app)
-- [Running your application](#running-your-application)
 - [Testing](#testing)
 - [Getting help](#getting-help)
 - [License](#license)
 
 ## Pre-requisites
-- [Node](https://nodejs.org)
-- [yarn](https://yarnpkg.com/getting-started/install)(recommended) or npm
-- [docker & docker-compose](https://docs.docker.com/engine/install/)
-- [ngrok account](https://ngrok.com/)
+- Install [Node.js](https://nodejs.org).
+- Install [yarn](https://yarnpkg.com/getting-started/install) (optional).
+- Install [Docker & Docker Compose](https://docs.docker.com/engine/install/).
+- Create an [ngrok](https://ngrok.com/) account.
+- Create an [Atlassian development site](http://go.atlassian.com/cloud-dev).
 
 ## Getting started
-You can run this app in 3 simple steps:
-- **Installing dependencies** 
-  - Run `yarn install` (recommended) or `npm install` for installing all the dependencies for this app.
 
-- **Configuration**
-  - We are using [ngrok](https://ngrok.com/docs/getting-started) for tunnelling. You'll need to create an ngrok 
-    account to get access to the auth token.
-  - Open your .env file and fill in *all the missing fields*
-
-- **Running docker compose** 
-  - Then simply run `docker-compose up`.
-  - Please be patient as it will take a few minutes for everything to be setup. When everything is setup, you should see the URL in the terminal as in the picture below. ![img.png](static/images/tunnel-output.png)
-
-> **Note:** _If you are using a free version of ngrok, please open the tunneled URL first. This needs to be done to bypass the ngrok browser warning. Just visit the ngrok warning page and just click on the Visit button._
+1. Install the dependencies.
+   ```shell
+   # If use Yarn (recommended)...
+   yarn install
+   # If use npm...
+   npm install
+   ```
+2. Create `.env` file based on `.env.example` and set the environment variables.
+3. Start the app and install it on Jira. Please be patient as it will take a few minutes for everything to be setup. When everything is set up, you should see the URL in the terminal as in the picture below.
+   ```shell
+   docker-compose up
+   ```
+   ![img.png](static/images/tunnel-output.png)
 
 At the very end, you can see the URL the index page of your app. Just open the URL and that's it, you're ready!
 
+> **Note:** _If you are using a free version of ngrok, please open the tunneled URL first. This needs to be done to bypass the ngrok browser warning. Just visit the ngrok warning page and just click on the "Visit" button._
+
 ## Manually Installing the App
-The above steps automatically installs the app, however you can only install one app at a time. 
-
-If you want to install the app in multiple Jira instances, please do it manually. Go to your Jira instances and do 
-the following steps:
-- From the header menu, select Apps -> Manage your apps.
-- Verify the filter is set to User-installed, and select Settings beneath the User-installed apps table.
-- On the Settings pop-up, add Enable development mode and click Apply. Refresh the page.
-- On the right side of the header, there should now appear a button Upload app. Click it and enter the app URL 
-  `/atlassian-connect.json`(`https://${APP_URL}/atlassian-connect.json`)
-- Click Upload.
-- That's it! You're done. 🎉
+
+The above steps automatically installs the app, however you can only install one app at a time.
+
+1. Go to your Jira instance.
+2. Enable the installation of apps that are not listed on the Atlassian Marketplace.
+    1. Go to **Apps** > **Manage your apps**.
+    2. Click **User-installed apps** > **Settings**.
+    3. Check **Enable development mode** and click **Apply**.
+3. Reload the page.
+4. Install the app.
+    1. Click **Upload app**.
+    2. Paste the link to your Connect descriptor (`${APP_URL}/atlassian-connect.json`) and
+       click **Upload**.
+
+That's it! You're done. 🎉
 
 ## Testing
-We have added a basic end to end test for installing and uninstalling the app, using [playwright](https://playwright.dev/docs/intro). You can add your own test cases on top of it. 
+We have added a basic end to end test for installing and uninstalling the app, using [playwright](https://playwright.dev/docs/intro). You can add your own test cases on top of it.
 
 To run the end to end test, please add the values for `ATLASSIAN_URL`, `JIRA_ADMIN_EMAIL` and `JIRA_ADMIN_API_TOKEN` in the `.env` file. Then simply run `yarn test:e2e` in the terminal.
 
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -5,7 +5,7 @@ services:
     image: wernight/ngrok
     ports:
       - "4040:4040"
-    command: ngrok http -log stdout --authtoken $NGROK_AUTHTOKEN app:3000
+    command: ngrok http -log stdout -hostname=$NGROK_DOMAIN --authtoken $NGROK_AUTHTOKEN app:3000
 
   app:
     container_name: connect-example-app-node
diff --git a/package.json b/package.json
@@ -11,9 +11,6 @@
     "clean:db": "rimraf db.json",
     "lint": "eslint . --ext .ts,.tsx",
     "build": "tsc --project .",
-    "postinstall": "ts-node postinstall.ts",
-    "prestart": "run-p clean prestart:wait",
-    "prestart:wait": "ts-node prestart.ts",
     "start": "tsnd --watch=.env,**/*.squirrelly --inspect=0.0.0.0:9229 --respawn --transpile-only -- src/server.ts",
     "test:e2e": "run-s test:e2e:install test:e2e:start",
     "test:e2e:debug": "PWDEBUG=1 run-s test:e2e:install test:e2e:headed",
diff --git a/postinstall.ts b/postinstall.ts
diff --git a/prestart.ts b/prestart.ts
diff --git a/src/routes/atlassian-connect.ts b/src/routes/atlassian-connect.ts
@@ -27,8 +27,6 @@ export const connectAppDescriptor = {
 
 	/**
 	 * The base url of the server, which is used for all communications between Connect and the app.
-	 *
-	 * The tunneled URL which is set in the `prestart.ts`
 	 */
 	baseUrl: envVars.APP_URL,
 
diff --git a/src/views/content/config.md b/src/views/content/config.md
@@ -6,8 +6,7 @@ app descriptor is:
 - `name`: the name of the Connect app
 - `description`: description for the Connect app
 - `key`: a unique key to identify your Connect app. This key must be <= 64 characters
-- `baseUrl`: The base url of the remote app, which is used for all communications back to the app instance. For this
-  example app, this is the tunneled URL which is set in the `prestart.ts`
+- `baseUrl`: The base url of the remote app, which is used for all communications back to the app instance.
 - `vendor`: the vendor who is offering this Connect app
 - `authentication`: this defines the authentication type to use when signing requests between the host application 
 and the Connect app. The supported types include `jwt`, `JWT`, `none`, `NONE`. We'll go into more detail around 
