Dockerised project to run it locally without much work

.gitignore

@@ -40,3 +40,7 @@ certificates
 /playwright-report/
 /blob-report/
 /playwright/.cache/
+
+# docker
+npm-cache
+.cache

Makefile

@@ -0,0 +1,49 @@
+SHELL := /usr/bin/env bash
+
+check_uid_set:
+	if [ -z "$(UID)" ]; then echo "UID variable required, please run 'export UID' before running make task"; exit 1 ; fi
+	if [ -z "$(WIX_NGROK_DOMAIN)" ]; then echo "WIX_NGROK_DOMAIN variable required, please set it up in your shell"; exit 1 ; fi
+
+up: check_uid_set npm_install
+	export UID && docker-compose up -d --force-recreate
+	bin/wait_for_docker.bash "Ready in"
+
+logs_tail: check_uid_set
+	export UID && docker-compose logs -f
+
+down:
+	docker-compose down
+
+build:
+	docker-compose build
+
+bash:
+	export UID && docker-compose run --rm node bash
+
+npm_install:
+	export UID && docker-compose run --rm node npm install
+
+npm_watch:
+	export UID && docker-compose run --rm node npm run watch
+
+npm_build:
+	export UID && docker-compose run --rm node npm run build
+
+npm_lint:
+	export UID && docker-compose run --rm node npm run lint
+
+npm_audit: check_uid_set
+	export UID && docker-compose run --rm node npm audit
+
+npm_audit_fix: check_uid_set
+	export UID && docker-compose run --rm node npm audit fix
+
+docker_clean:
+	docker rm $(docker ps -a -q) || true
+	docker rmi < echo $(docker images -q | tr "\n" " ")
+
+ngrok_free:
+	ngrok http
+
+ngrok_static: check_uid_set
+	ngrok http --domain="$(WIX_NGROK_DOMAIN)" 3000

README.md

@@ -11,14 +11,14 @@ The template handles common app functionalities, laying the groundwork for furth
 
 [Wix apps](https://dev.wix.com/docs/build-apps) enhance the functionality of Wix sites by adding new features such as custom pages, dashboard components, third-party integrations, or site analytics. Starting with an app template fast-tracks the development process, providing a working foundational app that developers can modify and build upon. This approach saves valuable time, allowing for a quick transition from concept to a fully functional app.
 
-Learn more about [Wix app templates](https://dev.wix.com/docs/build-apps/developer-tools/templates-and-examples/get-started-from-an-app-template) and explore our growing [template collection](https://dev.wix.com/apps-templates).
+Learn more about [Wix app templates](https://dev.wix.com/docs/build-apps/get-started/templates/get-started-from-an-app-template) and explore our growing [template collection](https://dev.wix.com/apps-templates).
 
 
 ## Template features
 
 This Wix app template incorporates the following features:
 
-+ **Self-hosting:** Develop and host an app on any platform, and integrate with Wix using the Wix Dev Center.
++ **Self-hosting:** Develop and host an app on any platform, and integrate with Wix using the App Dashboard.
 + **OAuth:** Secure authentication flow following Wix's guidelines.
 + **Wix Design System:** Utilize Wix's reusable React components for a cohesive user experience consistent with Wix's design standards.
 + **Wix Dashboard SDK:** Integrate custom dashboard components with the Wix site dashboard.
@@ -32,14 +32,17 @@ Before getting started, make sure you have the following set up:
 
 + [Node.js](https://nodejs.org/en/) (v18.16.0 or higher).
 + A [Wix developer account](https://users.wix.com/signin?loginDialogContext=signup&referralInfo=HEADER&postLogin=https:%2F%2Fdev.wix.com%2Fdc3%2Fmy-apps&postSignUp=https:%2F%2Fdev.wix.com%2Fdc3%2Fmy-apps&forceRender=true).
++ Docker (optional) to run it locally
++ Make (optional) to run application locally without calling docker commands manually
++ [Ngrok](https://ngrok.com/blog-post/free-static-domains-ngrok-users) ideally using a static URL
 
 
 ## Deploy to a free hosting service
 
 This template supports [quick deployment on Vercel or Netlify](https://dev.wix.com/apps-templates/template?id=0580022b-625e-4467-9f78-28cc3e618483) so you can get your app up and running in minutes. With quick deployment, you can:
 
 + Clone the app template repo and deploy a live app server instantly.
-+ Generate a pre-configured app in the [Wix Dev Center](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/get-started-with-the-wix-developers-center). For configuration details, read about [what deployment gives you](#what-deployment-gives-you).
++ Generate a pre-configured app in the [App Dashboard](https://dev.wix.com/docs/build-apps/develop-your-app/app-dashboard-setup/about-the-app-dashboard). For configuration details, read about [what deployment gives you](#what-deployment-gives-you).
 
 For instructions, go to the [app template page](https://dev.wix.com/apps-templates/template?id=0580022b-625e-4467-9f78-28cc3e618483).
 
@@ -54,9 +57,9 @@ To deploy the template on any other platform, follow these steps:
 Follow your platform's instructions to clone the repo and deploy the app server, then find and copy the deployment domain. This is the base URL for your app's server.
 
 
-### Step 2 | Generate a pre-configured Wix Dev Center app
+### Step 2 | Generate a pre-configured App Dashboard app
 
-To generate an app in the [Wix Dev Center](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/get-started-with-the-wix-developers-center) and pre-configure it automatically for the template:
+To generate an app in the [App Dashboard](https://dev.wix.com/docs/build-apps/develop-your-app/app-dashboard-setup/about-the-app-dashboard) and pre-configure it automatically for the template:
 
 1. On the template page, click **Use Template**.
 
@@ -68,7 +71,7 @@ To generate an app in the [Wix Dev Center](https://dev.wix.com/docs/build-apps/d
 
 1. Click **Create & Continue**.
 
-This creates an app for you in the Wix Dev Center with the required URLs and permissions pre-configured.
+This creates an app for you in the App Dashboard with the required URLs and permissions pre-configured.
 
 
 ### Step 3 | Configure environment variables
@@ -78,25 +81,26 @@ Once your app is created, a screen appears with a code snippet containing enviro
 + `WIX_APP_ID`: Your app's Wix App ID.
 + `WIX_APP_SECRET`: Your app's secret key.
 + `WIX_APP_JWT_KEY`: Your app's public key.
++ `URL`: this variable can be added and is optional if deploying locally. It is already used by Netlify and you can also use it locally if deploying with a custom domain like a Ngrok domain
 
 Save these environment variables as follows:
 
 1. Click **copy** to copy the code snippet to the clipboard.
 
-1. Create a file in your production root folder called `.env`, paste the code snippet into the file and save it.
+2. Create a file in your production root folder called `.env`, paste the code snippet into the file and save it.
 
     **Note:** Always keep your `.env` secure and never commit it to version control. This file contains sensitive keys that should not be exposed publicly.
 
-1. Redeploy the app.
+3. Redeploy the app.
 
 When deployment is finished, your app is ready to install.
 
 
 ### Step 4 | Test the app
 
-Follow these steps to create a [development site](https://dev.wix.com/docs/build-apps/developer-tools/cli/workflow/development-sites), install your app on the site, and try it out.
+Follow these steps to create a development site, install your app on the site, and try it out.
 
-1. In your app's page in the [Wix Dev Center](https://dev.wix.com/apps), click **Test Your App** in the top right, then click **Create Development Site**.
+1. In [your app's dashboard](https://dev.wix.com/apps), click **Test Your App** in the top right, then click **Create Development Site**.
 
 1. In the list of business solutions to install on the development site, click **Wix Stores**, then click **Create Site**.
 
@@ -113,13 +117,13 @@ Your app is now installed on your development site. To see the app's dashboard p
 
 ## What deployment gives you
 
-When you deploy this template, an app is automatically created for you in the [Wix Dev Center](https://dev.wix.com/apps/my-apps), pre-configured with settings required for the app to function properly within the Wix ecosystem. Find these pre-configured settings later in the app's dashboard as follows:
+When you deploy this template, an app is automatically created for you in the [App Dashboard](https://dev.wix.com/apps/my-apps), pre-configured with settings required for the app to function properly within the Wix ecosystem. Find these pre-configured settings later in the app's dashboard as follows:
 
-+ **OAuth page:** App URL and Redirect URL for the [app OAuth flow](https://dev.wix.com/docs/build-apps/build-your-app/authentication/oauth).
++ **OAuth page:** App URL and Redirect URL for the [advanced OAuth flow](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/use-advanced-oauth).
 
-+ **Webhooks page:** App Removed and App Installed [webhooks](https://dev.wix.com/docs/build-apps/build-your-app/authentication/authentication-overview#webhooks).
++ **Webhooks page:** App Removed and App Installed [webhooks](https://dev.wix.com/docs/build-apps/develop-your-app/api-integrations/events-and-webhooks/about-webhooks).
 
-+ **Extensions page:** Dashboard Page extension for the [dashboard page](https://dev.wix.com/docs/build-apps/developer-tools/extensions/dashboard-page#create-a-dashboard-page) and eCom Shipping Rates extension for [integrating with the Shipping Rates SPI](https://dev.wix.com/docs/rest/api-reference/wix-e-commerce/shipping-rates-integration-spi/introduction).
++ **Extensions page:** Dashboard Page extension for the [dashboard page](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/dashboard-extensions/dashboard-pages/about-dashboard-page-extensions) and eCom Shipping Rates extension for [integrating with the Shipping Rates SPI](https://dev.wix.com/docs/rest/api-reference/wix-e-commerce/shipping-rates-integration-spi/introduction).
 
 + **Permissions page:** [Permission scopes](https://dev.wix.com/docs/build-apps/build-your-app/authentication/permissions) required for the APIs that the app calls.
 
@@ -136,42 +140,50 @@ While developing your app, you may also wish to deploy and test it locally. You
     git clone <YOUR_REPO>
     ```
 
-1. Make sure you are in the repo's root folder, then install dependencies:
+2. Make sure you are in the repo's root folder, then install dependencies:
 
     ```shell
     npm install
     ```
+   **Note:** If using the dockerised approach locally this step is run as part of executing `make up` on the shell
 
-1. Create a file called `.env.local` in the repo's root folder. In that file, paste the required environment variables that you copied during quick deployment.
+3. Create a file called `.env.local` in the repo's root folder. In that file, paste the required environment variables that you copied during quick deployment.
 
-    If you didn't copy these values during quick deployment, you can retrieve them in the [Wix Dev Center](https://dev.wix.com/apps), then paste them in the following format:
+    If you didn't copy these values during quick deployment, you can retrieve them in the [App Dashboard](https://dev.wix.com/apps), then paste them in the following format:
 
     ```env
-    # App ID and App Secret Key: Retrieve from the OAuth page in the app's dashboard in the Wix Dev Center.
+    # App ID and App Secret Key: Retrieve from the OAuth page in the app's dashboard in the App Dashboard.
     APP_ID=<APP_ID>
     APP_SECRET=<APP_SECRET KEY>
 
-    # App Public Key: Retrieve from the Webhooks page in the app's dashboard in the Wix Dev Center.
+    # App Public Key: Retrieve from the Webhooks page in the app's dashboard in the App Dashboard.
     WEBHOOK_PUBLIC_KEY="<APP_WEBHOOK_PUBLIC_KEY>"
+
+    # URL for the local domain when running the app on your machine, ideally withh Ngrok if you need a public domain
+    # make sure the protocol prefix is included
+    URL=https://mydomain.ngrok....
     ```
 
     **Note:** Always keep your `.env.local` secure and never commit it to version control. This file contains sensitive keys that should not be exposed publicly.
 
-1. For the URLs configured in the Wix Dev Center, replace the app's base URL with `https://localhost:3000/`:
+4. For the URLs configured in the App Dashboard, replace the app's base URL with `https://localhost:3000/`:
 
-   + **OAuth page:** App URL and Redirect URL for the [app OAuth flow](https://dev.wix.com/docs/build-apps/build-your-app/authentication/oauth).
+   + **OAuth page:** App URL and Redirect URL for the [advanced OAuth flow](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/use-advanced-oauth).
 
-   + **Webhooks page:** App Removed and App Installed [webhooks](https://dev.wix.com/docs/build-apps/build-your-app/authentication/authentication-overview#webhooks).
+   + **Webhooks page:** App Removed and App Installed [webhooks](https://dev.wix.com/docs/build-apps/develop-your-app/api-integrations/events-and-webhooks/about-webhooks).
 
-1. To start the development server, enter:
+5. To start the development server, enter:
 
     ```shell
     npm run dev
     ```
+   If you would like to run it with Docker execute the followinr: 
+   - `make up` will run npm install and run dev, requires a UID and also expected a ngrok domain for the next step
+   - `make ngrok_static`, will run Ngrok locally against a fixed url as set in the `WIX_NGROK_DOMAIN` environment variable. Do not forget to add the [URL variable](#164) in .env.local
 
 You can now install the app on a Wix site with server code running locally.
 
-> **Note:** Remember to revert to the deployment URLs in the Wix Dev Center when you are ready to switch your app to production server deployment. You'll need to reinstall the app for the change to take effect.
+> **Note:** Remember to revert to the deployment URLs in the App Dashboard when you are ready to switch your app to production server deployment. You'll need to reinstall the app for the change to take effect.
 
 
 ## Extend and customize the app
@@ -181,7 +193,7 @@ The template is designed for easy customization and extension. Here are some sug
 
 ### Dashboard page customization
 
-The dashboard page is pre-integrated with the [Wix Design System](https://www.wixdesignsystem.com/) and [Wix Dashboard SDK](https://dev.wix.com/docs/sdk/api-reference/dashboard/introduction), providing a simple user interface that includes support for server-side rendering. It includes navigation to other relevant pages and an example of a shipping delivery form, and it utilizes the [Wix Data API](https://dev.wix.com/docs/sdk/api-reference/data/items/query-data-items) to query and present the last three orders in the dashboard. It utilizes both [client-side](./src/app/utils/wix-sdk.client-only.ts) and [server-side](./src/app/utils/wix-sdk.ts)(can be used from the client too, but would increase bundle size) SDK implementations.
+The dashboard page is pre-integrated with the [Wix Design System](https://www.wixdesignsystem.com/) and [Wix Dashboard SDK](https://dev.wix.com/docs/sdk/host-modules/dashboard/introduction), providing a simple user interface that includes support for server-side rendering. It includes navigation to other relevant pages and an example of a shipping delivery form, and it utilizes the [Wix Data API](https://dev.wix.com/docs/sdk/api-reference/data/items/query-data-items) to query and present the last three orders in the dashboard. It utilizes both [client-side](./src/app/utils/wix-sdk.client-only.ts) and [server-side](./src/app/utils/wix-sdk.ts)(can be used from the client too, but would increase bundle size) SDK implementations.
 
 Customize the dashboard page to fit your specific needs, whether it's updating the UI or adding new features.
 
@@ -216,7 +228,7 @@ This endpoint is crucial for customizing the logic used to calculate shipping ra
 
 ### Webhooks support
 
-The template implements support for two app lifecycle [webhooks](https://dev.wix.com/docs/build-apps/developer-tools/apis-and-webhooks/webhooks).
+The template implements support for two app lifecycle [webhooks](https://dev.wix.com/docs/build-apps/develop-your-app/api-integrations/events-and-webhooks/about-webhooks).
 
 **Development entry points:**
 + [`src/app/api/webhooks/v1/install/route.ts`](./src/app/api/webhooks/v1/install/route.ts) receives a payload when the app is installed.
@@ -255,6 +267,6 @@ To update the screenshots, trigger the workflow manually, and set the `shouldUpd
 
 For more information:
 
-+ Learn more about [Wix app templates](https://dev.wix.com/docs/build-apps/developer-tools/templates-and-examples/get-started-from-an-app-template).
++ Learn more about [Wix app templates](https://dev.wix.com/docs/build-apps/get-started/templates/get-started-from-an-app-template).
 + Check out our [full collection of app templates](https://dev.wix.com/apps-templates).
 + See our documentation for details about [building Wix apps](https://dev.wix.com/docs/build-apps).

bin/wait_for_docker.bash

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+waitForDocker () {
+    # wait until we see the required logs
+    WAIT_LOG=$1
+
+    MAX_ATTEMPTS=30
+    ATTEMPTS=0
+    while [ $ATTEMPTS -le $MAX_ATTEMPTS ]; do
+        ATTEMPTS=$(( ATTEMPTS + 1 ))
+
+        echo "Waiting for container log FRASE $WAIT_LOG - (attempt: $ATTEMPTS)..."
+        DOCKER_LOGS=$(docker-compose logs )
+        if grep -q "$WAIT_LOG" <<< "$DOCKER_LOGS" ; then
+          echo "Containers are Ready!"
+          break
+        else
+          echo "Containers NOT Ready!"
+        fi
+        sleep 2
+    done
+
+    # https://github.com/koalaman/shellcheck/wiki/SC2181
+    if ! grep -q "$WAIT_LOG" <<< "$DOCKER_LOGS" ; then
+      echo "Containers are not ready, tests will not run!"
+      exit 1
+    fi
+}
+
+waitForDocker "$@"

docker-compose.yml

@@ -0,0 +1,22 @@
+services:
+  node:
+    image: node:lts
+    volumes:
+      - websrc:/project
+    environment:
+      HOME: .
+      npm_config_cache: npm-cache
+    command: [ "npm", "run", "dev" ]
+    working_dir: /project
+    user: $UID
+    ports:
+      - "3000:3000"
+    env_file: ".env.local"
+
+volumes:
+  websrc:
+    driver: local
+    driver_opts:
+      o: bind
+      type: none
+      device: $PWD