Merge pull request #3 from iZettle/tweak-readme

Update README to align it with DevX documentation

README.md

@@ -1,11 +1,12 @@
 # Zettle Example Integration
 
 - [Introduction](#introduction) 
-- [Structure](#structure)
+  - [Structure](#structure)
+- [Prerequisites](#prerequisites)
 - [Instructions](#instructions)
-  - [Dependencies](#dependencies)
-  - [Environment variables](#environment-variables)
-  - [Docker](#running-via-docker)
+  - [Step 1: Environment variables](#step-1-environment-variables)
+  - [Step 2: Running via Docker](#step-2-running-via-docker)
+- [Subprojects](#subprojects)
 - [Certificates](#certificates)
 
 ## Introduction
@@ -16,7 +17,7 @@ You'll be able to clone this repository down and follow instructions to start we
 
 This code is intended to be used as reference material rather than being copied verbatim.
 
-## Structure
+### Structure
 
 This repository contains everything integrators need to run the project in one place, and is split into three sections:
 
@@ -26,22 +27,32 @@ This repository contains everything integrators need to run the project in one p
 
 The first version is designed to be run on macOS (we assume the presence of `brew`), but could be extended to run on other operating systems too, if there's demand.
 
+## Prerequisites
+* You have an account for the [Developer Portal](https://developer.zettle.com/). If you don't have an account, [sign up for a developer account](https://developer.zettle.com/register).
+* You have API credentials for the app. If you don't have any, [get API credentials for authorisation code grant](https://developer.zettle.com/applications/create/public).
+
 ## Instructions
-### Dependencies
-Prior to starting the project locally you'll need to install dependencies for the server and the web app. Instructions on doing this are:
 
-- [Web app readme](./web/README.md#installing-dependencies)
-- [Server readme](./server/README.md#dependencies)
+### Step 1: Environment variables
+Prepare environment variables in each subproject, so that the example app can use your developer credentials.
 
-If you encounter difficulties running the project via Docker, ensure the above steps are completed first. 
+#### Server
+* Copy `/server/.env.example` to `/server/.env`
+* Modify the variables that say `CHANGE_ME` to your own details
 
-### Environment variables
-There are some settings that need to be populated in each project so that the code can use your [developer.zettle.com](https://developer.zettle.com) credentials.
+Detailed description of the variables and what they do:
 
-You should create a Public API Application here to get these values https://developer.zettle.com/applications/create/public 
+| Environment Variable| Value | Notes |
+|----|-----|----|
+| ZETTLE_OAUTH_BASE_URL | `https://oauth.zettle.com` | |
+| ZETTLE_OAUTH_CLIENT_ID | UUID string | The client ID of your public app |
+| ZETTLE_OAUTH_CLIENT_SECRET | String | The client secret for your public app |
 
 #### Web
-These are set in `/web/.env`. An example set of values is provided at `/web/.env.example`
+* Copy `/web/.env.example` to `/web/.env`
+* You don't need to change anything in this file
+
+Detailed description of the variables and what they do:
 
 | Environment Variable| Value | Notes |
 |----|-----|----|
@@ -50,24 +61,34 @@ These are set in `/web/.env`. An example set of values is provided at `/web/.env
 | SSL_KEY_FILE | File path string | For development server use |
 | DISABLE_ESLINT_PLUGIN | Boolean | Set to false to enforce lint/format rules |
 | REACT_APP_SERVER_URL | URL:PORT string | Change this if you run the server at a different address |
-| REACT_APP_ZETTLE_OAUTH_URL | https://oauth.zettle.com | |
-| REACT_APP_ZETTLE_OAUTH_CLIENT_ID | UUID string | The client ID within your public app |
 
-#### Server
-These are set in `/server/.env`. An example set of values is provided at `/server/.env.example`
+### Step 2: Running via Docker
+To start both the server and web frontend you can execute the `./docker-run.sh` script in the root of this repository.
 
-| Environment Variable| Value | Notes |
-|----|-----|----|
-| ZETTLE_OAUTH_BASE_URL | https://oauth.zettle.com | |
-| ZETTLE_OAUTH_CLIENT_ID | UUID string | The client ID within your public app |
-| ZETTLE_OAUTH_CLIENT_SECRET | String |The client secret within your public app |
+This script:
+* Creates necessary self-signed TLS certificates
+* Builds the web app
+* Builds the server app
+* Runs both in Docker containers
 
-### Running via Docker
-To start both the server and web frontend you can execute the `./docker-run.sh` script in the root of this repository.
-This will create docker images for both components of the example integration and then run them. You can verify that
-the apps are running in the docker dashboard following the completion of the script.
+You should see that Docker has run both containers when the script finishes, like so:
+```
++ docker compose up -d
+[+] Running 2/2
+ ⠿ Container example-integration-server-1  Started                                                               0.5s
+ ⠿ Container example-integration-web-1     Started                                                               0.5s
+```
+
+Now the example app will be running and you can view it in your browser at https://localhost:3000/
+
+## Subprojects
+
+If you encounter problems running the project with Docker, you can set things up manually by following the README files in the web and server subprojects:
+
+- [Web app readme](./web/README.md#installing-dependencies)
+- [Server readme](./server/README.md#dependencies)
 
 ## Certificates
 The project uses a tool called `mkcert` to install self-signed certificates to use in both the server and web projects. It's automatically installed during the `docker-run.sh` process, and marks these certificates as valid in your browser (tested by us with Firefox).
 
-If you want to run either of the projects independently, you'll need run `create-certificate.sh` once to generate the required certificates first.
+If you want to run either of the projects independently, you'll need to run `create-certificate.sh` once to generate the required certificates first.

docker-run.sh

@@ -9,4 +9,4 @@ cd web && ./build-image.sh
 cd ../server && ./build-image.sh
 
 cd ../
-docker compose up -d
+docker compose up -d

server/.env.example

@@ -1,3 +1,3 @@
 ZETTLE_OAUTH_BASE_URL=https://oauth.zettle.com
-ZETTLE_OAUTH_CLIENT_ID=
-ZETTLE_OAUTH_CLIENT_SECRET=
+ZETTLE_OAUTH_CLIENT_ID=CHANGE_ME
+ZETTLE_OAUTH_CLIENT_SECRET=CHANGE_ME

web/.env.example

@@ -2,6 +2,4 @@ HTTPS=true
 SSL_CRT_FILE=./localhost.crt
 SSL_KEY_FILE=./localhost.key
 DISABLE_ESLINT_PLUGIN=true
-REACT_APP_SERVER_URL=https://localhost:8001
-REACT_APP_ZETTLE_OAUTH_URL=https://oauth.zettle.com
-REACT_APP_ZETTLE_OAUTH_CLIENT_ID=
+REACT_APP_SERVER_URL=https://localhost:8001