|
15 | 15 |
|
16 | 16 | Welcome! 👋👋🏿👋🏽👋🏻👋🏾👋🏼 |
17 | 17 |
|
18 | | -PASS is an open source digital wallet for providing home insecure individuals a safe place to store documents within their control. PASS additionally aims to assist caseworkers with processing and providing documents needed to complete the housing assistance application process. |
| 18 | +PASS is an open source digital wallet for providing home-insecure individuals a safe place to store documents within their control. PASS additionally aims to assist caseworkers with processing and providing documents needed to complete the housing-assistance application process. |
19 | 19 |
|
20 | | -The [PASS wiki](https://github.com/codeforpdx/PASS/wiki) contains detailed information of all things PASS including contribution guidelines, tech stack, information on SOLID, ect... |
| 20 | +This document is intended to be a crash course to get you up and running. The [PASS wiki](https://github.com/codeforpdx/PASS/wiki) is the place to go for detailed information of all things PASS including contribution guidelines, tech stack, information on SOLID, etc... |
21 | 21 |
|
22 | | -PASS is currently in development working towards MVP release by generous efforts from [our contributors](https://github.com/codeforpdx/PASS/graphs/contributors |
23 | | -). |
| 22 | +PASS is currently in development working towards MVP release by generous efforts from [our contributors](https://github.com/codeforpdx/PASS/graphs/contributors). |
24 | 23 |
|
25 | 24 | ## Contents |
26 | 25 |
|
27 | | -1. [Setup Instructions](#1-setup-instructions) |
28 | | -2. [Project Overview](#2-project-overview) |
29 | | -3. [Contribution Guidelines](#3-contribution-guidelines) |
30 | | -4. [Code of Conduct](#4-code-of-conduct) |
| 26 | +1. [Setup Instructions](#1-quick-setup-instructions) |
| 27 | +2. [Project Overview](#2-project-overview) |
| 28 | +3. [Contribution Guidelines](#3-contribution-guidelines) |
| 29 | +4. [Code of Conduct](#4-code-of-conduct) |
| 30 | +5. [PASS Wiki](#5-pass-wiki) |
31 | 31 |
|
32 | | -## 1. Setup Instructions |
| 32 | +## 1. Quick Setup Instructions |
33 | 33 |
|
34 | | -- ### Prerequisites |
| 34 | + **Note**: All commands in this document are for bash. If you are using an incompatible shell like CMD or powershell, you may need to use different commands. |
35 | 35 |
|
36 | | - Currently we require Node version 16.20.2 and NPM for our package manager. We recommend managing node and npm using Node Version Manager (NVM). To do so: |
| 36 | +- ### Getting the Code |
| 37 | + |
| 38 | +1. Clone the git repository: |
| 39 | + |
| 40 | + ```bash |
| 41 | + git clone https://github.com/codeforpdx/PASS.git |
| 42 | + ``` |
| 43 | +2. Enter the project folder: |
| 44 | + ```bash |
| 45 | + cd PASS |
| 46 | + ``` |
| 47 | + |
| 48 | +- ### Setting up Node |
| 49 | + |
| 50 | +_If you already have node 18 installed on your system, you may skip this section._ |
| 51 | + |
| 52 | +Currently, we require Node version 18.19.x and NPM for our package manager. We recommend using Node Version Manager (NVM) to install Node and npm. To proceed using NVM, perform the following: |
37 | 53 |
|
38 | 54 | 1. Download NVM for your system. |
39 | 55 |
|
40 | | -- For Mac, Linux, and other POSIX users: https://github.com/nvm-sh/nvm |
41 | | -- For Windows users: https://github.com/coreybutler/nvm-windows |
| 56 | +- For Mac, Linux, and other POSIX users: [https://github.com/nvm-sh/nvm](https://github.com/nvm-sh/nvm) |
| 57 | +- For Windows users: [https://github.com/coreybutler/nvm-windows](https://github.com/coreybutler/nvm-windows) |
42 | 58 |
|
43 | | -2. Install node version 16.20.2: |
44 | | - ``` |
45 | | - nvm install 16.20.2 |
46 | | - ``` |
47 | | -3. Use that node version: |
48 | | - ``` |
49 | | - nvm use 16.20.2 |
50 | | - ``` |
51 | | -4. Check that node and npm are set up: |
| 59 | +2. If you don't have node version 18, install node version 18 by running: |
| 60 | + ```bash |
| 61 | + nvm install 18 |
52 | 62 | ``` |
| 63 | + This will download node 18 and set it up for use |
| 64 | +3. Check that node and npm are set up: |
| 65 | +
|
| 66 | + ```bash |
53 | 67 | node -v |
54 | | - npm -v |
55 | 68 | ``` |
56 | | - If either of those commands error, node has not been installed correctly. |
57 | | - |
58 | | -- ### Clone and Install Dependencies |
59 | 69 |
|
60 | | -1. Clone the git repository: |
61 | | - ``` |
62 | | - git clone https://github.com/codeforpdx/PASS.git |
| 70 | + ```bash |
| 71 | + npm -v |
63 | 72 | ``` |
64 | | -2. Install project dependencies: |
| 73 | +The node version should be 18.19 (and maybe third decimal) and the npm version should be 10.2 (and maybe a third decimal). If they are not these versions, or if either of those commands cause an error, node has not been installed correctly. |
| 74 | +
|
| 75 | +4. We include a `.nvmrc` in the root folder of the project, which contains our target node version. We update this version periodically. If you're ever not sure of what node version you should be using, run |
| 76 | + ```bash |
| 77 | + nvm use |
65 | 78 | ``` |
| 79 | + to be synced with the project. You may receive warning messages in the terminal if the verion is not installed. Follow the messages to resolve the issues. |
| 80 | + |
| 81 | +- ### Set Up and Run the Project |
| 82 | + |
| 83 | +1. Install project dependencies: |
| 84 | + |
| 85 | + ```bash |
66 | 86 | npm install |
67 | 87 | ``` |
68 | | -3. Install the pre-commmit prettier, linter, and test hooks. |
69 | | - ``` |
70 | | - npm run prepare |
71 | | - ``` |
72 | | -4. Run the project: |
73 | | - ``` |
74 | | - npm run dev |
75 | | - ``` |
76 | | -5. PASS should launch at `http://localhost:5173`. You can now visit that url, and sign into a pod hosted at the OIDC provider of your choice. |
77 | 88 |
|
78 | | -- ### Setting up a Development Pod Server |
79 | | - PASS is able to connect to any solid-spec compliant pod server. However, for testing, it's recommended that you run a server locally. PASS provides tools to make this easy to do. |
| 89 | +2. Configure the project environment: |
| 90 | + ```bash |
| 91 | + cp env.template .env |
| 92 | + ``` |
80 | 93 |
|
81 | | -1. Clone and install dependencies. [See previous section](#clone-and-install-dependencies) |
| 94 | +3. Run the following command: |
| 95 | + ```bash |
| 96 | + npm start |
| 97 | + ``` |
| 98 | + To start up everything needed to run PASS. |
82 | 99 |
|
83 | | -2. In the project's root directory, copy the `env.template` file into a `.env` file. In bash you can use this command: |
| 100 | +4. Navigate to PASS and set up an account. |
84 | 101 |
|
85 | | - ```bash |
86 | | - cp env.template .env |
87 | | - ``` |
| 102 | + By default, PASS launches at [http://localhost:5173](http://localhost:5173) on your local machine. Navigate to that screen, then click the signup button to create a pod and web ID for yourself. Then return to the homepage and log in. Follow all prompts that appear, and you will be up and running with PASS! |
88 | 103 |
|
89 | | -3. Run `npm run podserver` to launch the pod server. The server will begin listening on `http://localhost:3000`, and will create a folder in the PASS project folder called `local_temp_server_files`. You can find all server and pod files there. |
| 104 | +- ### Setting up Git Hooks for development |
90 | 105 |
|
91 | | -4. Open a browser and navigate to `http://localhost:3000`. You should encounter a screen asking you to set up the server and create an account. Create your first account, and your server will be ready for development. |
| 106 | +We require all code contributed to the project to pass through our git hooks. To set them up, do the following: |
92 | 107 |
|
93 | | -5. Launch PASS with `npm run dev`. Click the `Login` button on the home page. If everything has been set up right, you should be redirected to your local pod server to finish login. |
| 108 | +1. Install the pre-commmit prettier and linter hooks. |
94 | 109 |
|
95 | | -Note: The `npm run podserver` command will launch a server that stores documents on your local file system. If you don't want to store documents, and want all server data to be deleted on shutdown, you can run `npm run podserver:temp` |
| 110 | + ```bash |
| 111 | + npm run prepare |
| 112 | + ``` |
96 | 113 |
|
97 | 114 | ## 2. Project Overview |
98 | 115 |
|
99 | | -In Portland, housing insecure individuals struggle to maintain documents often required to receive government and/or non-profit services. With PASS, we are building out an application to enable housing insecure individuals to store their personal documents in decentralized data stores, called Pods. PASS will also provide a platform for Organizations to assist with providing and processing documents required for housing assistance. Using [Solid Data Pods](https://solidproject.org/) individuals will have control over which organizations and applications can access their data. Verified organizations will be able to use PASS to request data from an individual and/or add documents (such as references or invoices) to an individuals pod to help process housing assistance applications. |
| 116 | +In Portland, housing-insecure individuals struggle to maintain documents often required to receive government and/or non-profit services. With PASS, we are building out an application to enable housing-insecure individuals to store their personal documents in decentralized data stores, called Pods. PASS will also provide a platform for organizations to assist with providing and processing documents required for housing assistance. Using [Solid Data Pods](https://solidproject.org/) individuals will have control over which organizations and applications can access their data. Verified organizations will be able to use PASS to request data from an individual and/or add documents (such as references or invoices) to an individual's Pod to help process housing assistance applications. |
100 | 117 |
|
101 | 118 | ## 3. Contribution Guidelines |
102 | 119 |
|
103 | | -- Start by checking out the detailed on-boarding [CONTRIBUTING.md](./docs/CONTRIBUTING.md). |
104 | | -- Join our [Discord](https://discord.gg/Ts923xaUYV) and self assign roles as you see fit. [](https://discord.gg/Ts923xaUYV) |
| 120 | +- Start by checking out the detailed onboarding [in the Wiki](https://github.com/codeforpdx/PASS/wiki/Development#contribution-guidelines). |
| 121 | +- Join our [Discord](https://discord.gg/Ts923xaUYV) and self-assign roles as you see fit. [](https://discord.gg/Ts923xaUYV) |
105 | 122 | - Request git-hub access on Discord in the [github-access-request](https://discord.com/channels/1068260532806766733/1078124139983945858) channel of the General category. |
106 | 123 |
|
107 | 124 | ## 4. Code of Conduct |
108 | 125 |
|
109 | | -- [Code for PDX code of conduct](https://github.com/codeforpdx/codeofconduct/blob/master/README.md) |
| 126 | +- [CODEPDX code of conduct](https://github.com/codeforpdx/codeofconduct/blob/master/README.md) |
| 127 | +
|
| 128 | +## 5. PASS Wiki |
| 129 | +[Visit the wiki for more information on every aspect of the project. Feature set, architecture, tooling, etc](https://github.com/codeforpdx/PASS/wiki) |
110 | 130 |
|
111 | 131 | **[⬆️ Back to Top](#pass---personal-access-system-for-services)** |
0 commit comments