diff --git a/docs/images/04-pwa-chrome-devtools.png b/docs/images/04-pwa-chrome-devtools.png new file mode 100644 index 000000000..f33976283 Binary files /dev/null and b/docs/images/04-pwa-chrome-devtools.png differ diff --git a/docs/images/05-pwa-account-button.png b/docs/images/05-pwa-account-button.png new file mode 100644 index 000000000..e96850ec0 Binary files /dev/null and b/docs/images/05-pwa-account-button.png differ diff --git a/docs/images/06-pwa-account-page.png b/docs/images/06-pwa-account-page.png new file mode 100644 index 000000000..5f73f623b Binary files /dev/null and b/docs/images/06-pwa-account-page.png differ diff --git a/docs/images/07-pwa-did-copied.png b/docs/images/07-pwa-did-copied.png new file mode 100644 index 000000000..eeff26611 Binary files /dev/null and b/docs/images/07-pwa-did-copied.png differ diff --git a/docs/images/08-endorser-sqlite-row-added.png b/docs/images/08-endorser-sqlite-row-added.png new file mode 100644 index 000000000..392a6054a Binary files /dev/null and b/docs/images/08-endorser-sqlite-row-added.png differ diff --git a/docs/images/09-pwa-second-profile-first-open.png b/docs/images/09-pwa-second-profile-first-open.png new file mode 100644 index 000000000..981431894 Binary files /dev/null and b/docs/images/09-pwa-second-profile-first-open.png differ diff --git a/docs/images/10-pwa-second-user-did.png b/docs/images/10-pwa-second-user-did.png new file mode 100644 index 000000000..d03de1b28 Binary files /dev/null and b/docs/images/10-pwa-second-user-did.png differ diff --git a/docs/images/11-pwa-first-user-add-contact.png b/docs/images/11-pwa-first-user-add-contact.png new file mode 100644 index 000000000..d107ace9d Binary files /dev/null and b/docs/images/11-pwa-first-user-add-contact.png differ diff --git a/docs/images/12-pwa-first-user-contact-added.png b/docs/images/12-pwa-first-user-contact-added.png new file mode 100644 index 000000000..fe280cb33 Binary files /dev/null and b/docs/images/12-pwa-first-user-contact-added.png differ diff --git a/docs/images/13-pwa-first-user-register-second-user-btn.png b/docs/images/13-pwa-first-user-register-second-user-btn.png new file mode 100644 index 000000000..b1ead615c Binary files /dev/null and b/docs/images/13-pwa-first-user-register-second-user-btn.png differ diff --git a/docs/images/14-pwa-first-user-register-yes.png b/docs/images/14-pwa-first-user-register-yes.png new file mode 100644 index 000000000..fd402ba38 Binary files /dev/null and b/docs/images/14-pwa-first-user-register-yes.png differ diff --git a/docs/usage-guide.md b/docs/usage-guide.md index 01be16368..214ebf888 100644 --- a/docs/usage-guide.md +++ b/docs/usage-guide.md @@ -82,12 +82,12 @@ simplified guide illustrating how to gain value from using TimeSafari. This section is tailored for software developers seeking to use the application during development, quality assurance, and testing. -## Bootstrapping a local development environment +# Bootstrapping a local development environment The first concern a software developer has when working on TimeSafari is to set up a local development environment. This section will guide you through the process. -### Prerequisites +## Prerequisites 1. Have the following installed on your local machine: - Node.js and NPM @@ -103,112 +103,214 @@ development environment. This section will guide you through the process. Click "VIEW STATS" on the key you want to use. - ![](images/01_infura-api-keys.png) { width=350px } + ![](images/01_infura-api-keys.png){ width=550px } - Go to the key detail page. Then click "MANAGE API KEY". - ![](images/02-infura-key-detail.png) { width=350px } + ![](images/02-infura-key-detail.png){ width=550px } - Click the copy and paste button next to the string of alphanumeric characters.\ This is your API, also known as your project ID. - ![](images/03-infura-api-key-id.png) {width=350px } + ![](images/03-infura-api-key-id.png){width=550px } - Save this for later during the Endorser API setup. This will go in your `INFURA_PROJECT_ID` environment variable. -### Setup steps +## Setup steps -#### 1. Clone the following repositories from their respective Git hosts: +### 1. Clone the following repositories from their respective Git hosts: - [TimeSafari Frontend](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa)\ This is a Progressive Web App (PWA) built with VueJS and TypeScript. Note that the clone command here is different from the one you would use for GitHub. - ```bash - git clone git clone ssh://git@gitea.anomalistdesign.com:222/trent_larson/crowd-funder-for-time-pwa.git - ``` + +```bash +git clone git clone \ + ssh://git@gitea.anomalistdesign.com:222/trent_larson/crowd-funder-for-time-pwa.git +``` + - [TimeSafari Backend - Endorser API](https://github.com/trentlarson/endorser-ch)\ This is a NodeJS service providing the backend for TimeSafari. + ```bash git clone git@github.com:trentlarson/endorser-ch.git ``` \pagebreak -#### 2. Database creation +### 2. Database creation -##### Alternative 1 - use test data +#### Alternative 1 - use test data To generate a development database and perform user setup you can run a local test with instructions below to generate sample data. Then copy the test database, rename it to `-dev` as below:\ `cp ../endorser-ch-test-local.sqlite3 ../endorser-ch-dev.sqlite3` \ and rerun `npm run dev` to give yourself user #0 and others from the ETHR_CRED_DATA in [the endorser.ch test util file](https://github.com/trentlarson/endorser-ch/blob/master/test/util.js#L90) -##### Alternative 2 - boostrap single seed user - -1. In endorser-ch install dependencies and set up environment variables to allow starting it up in - development mode. - ```bash - cd endorser-ch - npm clean install # or npm ci - cp .env.local .env - ``` - Edit the .env file's INFURA_PROJECT_ID with the value you saved earlier in the - prerequisites.\ - Then create the SQLite database by running `npm run flyway migrate` with environment variables - set correctly to select the default SQLite development user as follows. - ```bash - export NODE_ENV=dev - export DBUSER=sa - export DBPASS=sasa - npm run flyway migrate - ``` - The first run of flyway migrate may take some time to complete because the entire Flyway - distribution must be downloaded prior to executing migrations. +#### Alternative 2 - boostrap single seed user + +In this method you will end up with two accounts in the database, one for the first boostrap user, +and the second as the primary user you will use during testing. The first user will invite the +second user to the app. + +1. Install dependencies and environment variables.\ + In endorser-ch install dependencies and set up environment variables to allow starting it up in + development mode. + ```bash + cd endorser-ch + npm clean install # or npm ci + cp .env.local .env + ``` + Edit the .env file's INFURA_PROJECT_ID with the value you saved earlier in the + prerequisites.\ + Then create the SQLite database by running `npm run flyway migrate` with environment variables + set correctly to select the default SQLite development user as follows. + ```bash + export NODE_ENV=dev + export DBUSER=sa + export DBPASS=sasa + npm run flyway migrate + ``` + The first run of flyway migrate may take some time to complete because the entire Flyway + distribution must be downloaded prior to executing migrations. - Successful output looks similar to the following: - ``` - Database: jdbc:sqlite:../endorser-ch-dev.sqlite3 (SQLite 3.41) - Schema history table "main"."flyway_schema_history" does not exist yet - Successfully validated 10 migrations (execution time 00:00.034s) - Creating Schema History table "main"."flyway_schema_history" ... - Current version of schema "main": << Empty Schema >> - Migrating schema "main" to version "1 - initial-anew" - Migrating schema "main" to version "2 - registration" - Migrating schema "main" to version "3 - plan project" - Migrating schema "main" to version "4 - offer gave" - Migrating schema "main" to version "5 - more confirmations" - Migrating schema "main" to version "6 - providers urls" - Migrating schema "main" to version "7 - hash nonce" - Migrating schema "main" to version "8 - project location" - Migrating schema "main" to version "9 - plan links" - Migrating schema "main" to version "10 - gift or trade" - Successfully applied 10 migrations to schema "main", now at version v10 (execution time 00:00.043s) - A Flyway report has been generated here: /Users/kbull/code/timesafari/endorser-ch/report.html - ``` + Successful output looks similar to the following: + +``` +Database: jdbc:sqlite:../endorser-ch-dev.sqlite3 (SQLite 3.41) +Schema history table "main"."flyway_schema_history" does not exist yet +Successfully validated 10 migrations (execution time 00:00.034s) +Creating Schema History table "main"."flyway_schema_history" ... +Current version of schema "main": << Empty Schema >> +Migrating schema "main" to version "1 - initial-anew" +Migrating schema "main" to version "2 - registration" +Migrating schema "main" to version "3 - plan project" +Migrating schema "main" to version "4 - offer gave" +Migrating schema "main" to version "5 - more confirmations" +Migrating schema "main" to version "6 - providers urls" +Migrating schema "main" to version "7 - hash nonce" +Migrating schema "main" to version "8 - project location" +Migrating schema "main" to version "9 - plan links" +Migrating schema "main" to version "10 - gift or trade" +Successfully applied 10 migrations to schema "main", now at version v10 (execution time 00:00.043s) +A Flyway report has been generated here: /Users/kbull/code/timesafari/endorser-ch/report.html +``` \pagebreak -2. Generate first user with the TimeSafari PWA and bootstrap that user.\ - In order to seed the SQLite database with the first registered user that user must first be - generated from the TimeSafari application. Bootstrapping that user is required so that you can - use that root user to register other users since TimeSafari is an invite-only platform. +2. Generate the first user in TimeSafari PWA and bootstrap that user in Endorser's database.\ + As TimeSafari is an invite-only platform the first user must be manually bootstrapped since + no other users exist to be able to invite the first user. This first user must be added manually + to the SQLite database used by Endorser. In this setup you generate the first user from the PWA. + + This user is automatically generated on first usage of the TimeSafari PWA. Bootstrapping that + user is required so that this first user can register other users. - Change directories into `crowd-funder-for-time-pwa` + ```bash cd .. cd crowd-funder-for-time-pwa ``` + + - Ensure the `.env.development` file exists and has the following values: + + ```env + VITE_DEFAULT_ENDORSER_API_SERVER=http://127.0.0.1:3000 + ``` + - Install dependencies and run in dev mode. For now don't worry about configuring the app. All we need is to generate the first root user and this happens automatically on app startup. + ```bash npm clean install # or npm ci npm run dev ``` + + - Open the app in a browser and go to the developer tools. It is recommended to use a completely + separate browser profile so you do not clear out your existing user account. We will be + completely resetting the PWA app state prior to generating the first user. + + In the Developer Tools go to the Application tab. + + ![](images/04-pwa-chrome-devtools.png){width=350px} + + Click the "Clear site data" button and then refresh the page. + + - Click the account button in the bottom right corner of the page. + + ![](images/05-pwa-account-button.png){width=150px} + + - This will take you to the account page titled "Your Identity" on which you can see your DID, + a `did:ethr` DID in this case. + + ![](images/06-pwa-account-page.png){width=350px} + + - Copy the DID by selecting it and copying it to the clipboard or by clicking the copy and paste + button as shown in the image. + + ![](images/07-pwa-did-copied.png){width=200px} + + In our case this DID is:\ + `did:ethr:0xe4B783c74c8B0e229524e44d0cD898D272E02CD6` + + - Add that DID to the following echoed SQL statement where it says `YOUR_DID` + + ```bash + echo "INSERT INTO registration (did, maxClaims, maxRegs, epoch) + VALUES ('YOUR_DID', 100, 10000, 1719348718092);" + | sqlite3 ./endorser-ch-dev.sqlite3 + ``` + + and run this command in the parent directory just above the `endorser-ch` directory. + + It needs to be the parent directory of your `endorser-ch` repository because when + `endorser-ch` creates the SQLite database it depends on it creates it in the parent directory + of `endorser-ch`. + + - You can verify with an SQL browser tool that your record has been added to the `registration` + table. + + ![](images/08-endorser-sqlite-row-added.png){width=350px} -4. Then start the service in development mode with the following commands. +3. Then start the Endorser service in development mode with the following commands. + ```bash + cd ./endorser-ch export NODE_ENV=dev npm run dev ``` - Then register the first permissioned user by adding a DID thus: - echo "INSERT INTO registration (did, maxClaims, maxRegs, epoch) VALUES ('YOUR_DID', 100, 10000, 1719348718092);" | sqlite3 ../endorser-ch-dev.sqlite3 + + This starts the Endorser service on port 3000. +4. Create the second user by opening up a separate browser profile or incognito session, opening the + TimeSafari PWA at `http://localhost:8080`. You will see the yellow banner stating "Someone must + register you before you can give or offer." + + ![](images/09-pwa-second-profile-first-open.png){width=350px} + + - If you want to ensure you have a fresh user account then open the developer tools, clear the + Application data as before, and then refresh the page. This will generate a new user in the + browser's IndexedDB database. +5. Go to the second users' account page to copy the DID. + + ![](images/10-pwa-second-user-did.png){width=350px} + +6. Copy the DID and put it in the text bar on the "Your Contacts" page for the first account + + ![](images/11-pwa-first-user-add-contact.png){width=350px} + +7. Click the "+" plus icon to add the user. + + ![](images/12-pwa-first-user-contact-added.png){width=350px} + +8. Then click the register button to register the second user. + + ![](images/13-pwa-first-user-register-second-user-btn.png){width=350px} + +9. Click "YES" on the dialog that shows up. + + ![](images/14-pwa-first-user-register-yes.png){width=350px} + + After this a notification will pop up indicating whether registration was successful or not. + +10. You have finished the initial set up of users.