Jose Olarte III
4 months ago
55 changed files with 1179 additions and 500 deletions
@ -0,0 +1,76 @@ |
|||
# TimeSafari Docs |
|||
|
|||
## Generating PDF from Markdown on OSx |
|||
|
|||
This uses Pandoc and BasicTex (LaTeX) Installed through Homebrew. |
|||
|
|||
### Set Up |
|||
|
|||
```bash |
|||
brew install pandoc |
|||
|
|||
brew install basictex |
|||
|
|||
# Setting up LaTex packages |
|||
|
|||
# First update tlmgr |
|||
sudo tlmgr update --self |
|||
|
|||
# Then install LaTex packages |
|||
sudo tlmgr install bbding |
|||
sudo tlmgr install enumitem |
|||
sudo tlmgr install environ |
|||
sudo tlmgr install fancyhdr |
|||
sudo tlmgr install framed |
|||
sudo tlmgr install import |
|||
sudo tlmgr install lastpage # Enables Page X of Y |
|||
sudo tlmgr install mdframed |
|||
sudo tlmgr install multirow |
|||
sudo tlmgr install needspace |
|||
sudo tlmgr install ntheorem |
|||
sudo tlmgr install tabu |
|||
sudo tlmgr install tcolorbox |
|||
sudo tlmgr install textpos |
|||
sudo tlmgr install titlesec |
|||
sudo tlmgr install titling # Required for the fancy headers used |
|||
sudo tlmgr install threeparttable |
|||
sudo tlmgr install trimspaces |
|||
sudo tlmgr install tocloft # Required for \tableofcontents generation |
|||
sudo tlmgr install varwidth |
|||
sudo tlmgr install wrapfig |
|||
|
|||
# Install fonts |
|||
sudo tlmgr install cmbright |
|||
sudo tlmgr install collection-fontsrecommended # And set up fonts |
|||
sudo tlmgr install fira |
|||
sudo tlmgr install fontaxes |
|||
sudo tlmgr install libertine # The main font the doc uses |
|||
sudo tlmgr install opensans |
|||
sudo tlmgr install sourceserifpro |
|||
|
|||
``` |
|||
|
|||
#### References |
|||
|
|||
The following guide was adapted to this project except that we install with Brew and have a few more packages. |
|||
|
|||
Guide: https://daniel.feldroy.com/posts/setting-up-latex-on-mac-os-x |
|||
|
|||
### 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 |
|||
``` |
|||
|
After Width: | Height: | Size: 61 KiB |
|
After Width: | Height: | Size: 40 KiB |
|
After Width: | Height: | Size: 77 KiB |
|
After Width: | Height: | Size: 140 KiB |
|
After Width: | Height: | Size: 4.6 KiB |
|
After Width: | Height: | Size: 62 KiB |
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 40 KiB |
|
After Width: | Height: | Size: 40 KiB |
|
After Width: | Height: | Size: 46 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 53 KiB |
|
After Width: | Height: | Size: 23 KiB |
|
After Width: | Height: | Size: 19 KiB |
|
After Width: | Height: | Size: 34 KiB |
|
After Width: | Height: | Size: 463 KiB |
@ -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. |
|||
|
|||
{ width=550px } |
|||
|
|||
- Go to the key detail page. Then click "MANAGE API KEY". |
|||
|
|||
{ 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. |
|||
|
|||
{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. |
|||
|
|||
{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. |
|||
|
|||
{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. |
|||
|
|||
{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. |
|||
|
|||
{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. |
|||
|
|||
{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." |
|||
|
|||
{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. |
|||
|
|||
{width=350px} |
|||
|
|||
6. Copy the DID and put it in the text bar on the "Your Contacts" page for the first account |
|||
|
|||
{width=350px} |
|||
|
|||
7. Click the "+" plus icon to add the user. |
|||
|
|||
{width=350px} |
|||
|
|||
8. Then click the register button to register the second user. |
|||
|
|||
{width=350px} |
|||
|
|||
9. Click "YES" on the dialog that shows up. |
|||
|
|||
{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. |
|||
@ -0,0 +1,10 @@ |
|||
/// <reference types="vite/client" />
|
|||
|
|||
interface ImportMetaEnv { |
|||
readonly VITE_APP_TITLE: string; |
|||
// more env variables...
|
|||
} |
|||
|
|||
interface ImportMeta { |
|||
readonly env: ImportMetaEnv; |
|||
} |
|||
Loading…
Reference in new issue