diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..25623708a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,66 @@ +# TimeSafari Docs + +## Generating PDF from Markdown on OSx + +This uses Pandoc and BasicTex (LaTeX) Installed through Homebrew. + +### Set Up + +```bash +# See https://daniel.feldroy.com/posts/setting-up-latex-on-mac-os-x +brew install pandoc + +brew install basictex + +pandoc keystore-migration.md -o keystore-migration.pdf + +# Setting up LaTex packages + +# First update tlmgr +sudo tlmgr update --self + +# Then install LaTex packages +sudo tlmgr install titlesec +sudo tlmgr install framed +sudo tlmgr install threeparttable +sudo tlmgr install wrapfig +sudo tlmgr install multirow +sudo tlmgr install enumitem +sudo tlmgr install bbding +sudo tlmgr install titling # Required for the fancy headers used +sudo tlmgr install tabu +sudo tlmgr install mdframed +sudo tlmgr install tcolorbox +sudo tlmgr install textpos +sudo tlmgr install import +sudo tlmgr install varwidth +sudo tlmgr install needspace +sudo tlmgr install tocloft # Required for \tableofcontents generation +sudo tlmgr install ntheorem +sudo tlmgr install environ +sudo tlmgr install trimspaces +sudo tlmgr install lastpage # Enables Page X of Y +sudo tlmgr install collection-fontsrecommended # And set up fonts +sudo tlmgr install libertine # The main font the doc uses + + +``` + +### Usage + +Use the `pandoc` command to generate a PDF. + +```bash +pandoc usage-guide.md -o usage-guide.pdf +``` + +And you can open the PDF with the `open` command. + +```bash +open usage-guide.pdf +``` + +Or use this one-liner +```bash +pandoc usage-guide.md -o usage-guide.pdf && open usage-guide.pdf +``` 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/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/images/timesafari-logo-binoculars.png b/docs/images/timesafari-logo-binoculars.png new file mode 100644 index 000000000..172fd1332 Binary files /dev/null and b/docs/images/timesafari-logo-binoculars.png differ diff --git a/docs/images/timesafari-logo.png b/docs/images/timesafari-logo.png new file mode 100644 index 000000000..ec8cb09f9 Binary files /dev/null and b/docs/images/timesafari-logo.png differ diff --git a/docs/usage-guide.md b/docs/usage-guide.md new file mode 100644 index 000000000..214ebf888 --- /dev/null +++ b/docs/usage-guide.md @@ -0,0 +1,316 @@ +--- +geometry: margin=1in +header-includes: + - \usepackage{graphicx} + - \usepackage{titling} + - \usepackage{fancyhdr} + - \usepackage{lastpage} + - \pagestyle{fancy} + - \fancyhead[L]{Time Safari Usage Guide} + - \fancyhead[C]{Page \thepage\ of \pageref{LastPage}} + - \fancyhead[R]{} + - \fancyfoot[L]{} + - \fancyfoot[C]{} + - \fancyfoot[R]{\includegraphics[width=1cm]{images/timesafari-logo-binoculars.png}} + - \usepackage{tocloft} + - \usepackage{libertine} + - \renewcommand{\familydefault}{\sfdefault} + - \fancypagestyle{tocstyle}{ + \fancyhead[L]{Time Safari Usage Guide} + \fancyhead[C]{Page \thepage\ of \pageref{LastPage}} + \fancyhead[R]{} + \fancyfoot[L]{} + \fancyfoot[C]{} + \fancyfoot[R]{\includegraphics[width=1cm]{images/timesafari-logo-binoculars.png}}} +--- + +\begin{titlepage} +\centering +\vspace*{\fill} +{\huge\textbf{TimeSafari Usage guide}} + +\vspace{1cm} +{\Large Signing up users, adding contacts, and adding gifts.} + +\vspace{1cm} +\includegraphics[width=0.5\textwidth]{images/timesafari-logo.png} +\vspace*{\fill} + +\vspace{1cm} +{\Large Trent Larson, Kent Bull} + +\vspace{0.5cm} +{\large 2024-06-25} + +\end{titlepage} + +\clearpage + +\begin{center} +\includegraphics[width=2cm]{images/timesafari-logo-binoculars.png} +\end{center} +\tableofcontents + +\clearpage + + +# Purpose of Document + +Both end-users and development team members need to know how to use TimeSafari. +This document serves to show how to use every feature of the TimeSafari platform. + +Sections of this document are geared specifically for software developers and quality assurance +team members. + +Companion videos will also describe end-to-end workflows for the end-user. + +# TimeSafari + +## Overview + +\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=550px } + + - Go to the key detail page. Then click "MANAGE API KEY". + + ![](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=550px } + + - 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 + +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 +``` + +\pagebreak + +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} + +3. Then start the Endorser service in development mode with the following commands. + + ```bash + cd ./endorser-ch + export NODE_ENV=dev + npm run dev + ``` + + 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.