diff --git a/docs/images/01_infura-api-keys.png b/docs/images/01_infura-api-keys.png new file mode 100644 index 000000000..2ea7519a9 Binary files /dev/null and b/docs/images/01_infura-api-keys.png differ diff --git a/docs/images/02-infura-key-detail.png b/docs/images/02-infura-key-detail.png new file mode 100644 index 000000000..fa29d5c18 Binary files /dev/null and b/docs/images/02-infura-key-detail.png differ diff --git a/docs/images/03-infura-api-key-id.png b/docs/images/03-infura-api-key-id.png new file mode 100644 index 000000000..ea242fc4e Binary files /dev/null and b/docs/images/03-infura-api-key-id.png differ diff --git a/docs/usage-guide.md b/docs/usage-guide.md index 527322911..01be16368 100644 --- a/docs/usage-guide.md +++ b/docs/usage-guide.md @@ -11,7 +11,7 @@ header-includes: - \fancyhead[R]{} - \fancyfoot[L]{} - \fancyfoot[C]{} - - \fancyfoot[R]{\includegraphics[width=1cm]{images/timesafari-logo.png}} + - \fancyfoot[R]{\includegraphics[width=1cm]{images/timesafari-logo-binoculars.png}} - \usepackage{tocloft} - \usepackage{libertine} - \renewcommand{\familydefault}{\sfdefault} @@ -68,6 +68,147 @@ Companion videos will also describe end-to-end workflows for the end-user. ## Overview -### End Users - -### Software Developers +\pagebreak + +# 1 - End Users + +This section covers application usage for people who will use TimeSafari as intended. It is a +simplified guide illustrating how to gain value from using TimeSafari. + +\pagebreak + +# 2 - Software Developers + +This section is tailored for software developers seeking to use the application during development, +quality assurance, and testing. + +## 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 + +1. Have the following installed on your local machine: + - Node.js and NPM + - A web browser. For this guide, we will use Google Chrome. + - Git + - A code editor + +2. Create an API key on Infura. This is necessary for the Endorser API to connect to the Ethereum + blockchain. + - You can create an account on Infura [here](https://infura.io/).\ + Click "CREATE NEW API KEY" and label the key. Then click "API Keys" in the top menu bar to + be taken back to the list of keys. + + Click "VIEW STATS" on the key you want to use. + + ![](images/01_infura-api-keys.png) { width=350px } + + - Go to the key detail page. Then click "MANAGE API KEY". + + ![](images/02-infura-key-detail.png) { width=350px } + + - 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 } + + - Save this for later during the Endorser API setup. This will go in your `INFURA_PROJECT_ID` + environment variable. + + +### Setup steps + +#### 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 + ``` + - [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 + +##### 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. + + 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. + - Change directories into `crowd-funder-for-time-pwa` + ```bash + cd .. + cd crowd-funder-for-time-pwa + ``` + - 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 + ``` + +4. Then start the service in development mode with the following commands. + ```bash + 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