Getting Started

Installation Instructions

Prerequisites

Currently, we require Node version 18.19.0 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:

1. Download NVM for your system.

• For Mac, Linux, and other POSIX users: https://github.com/nvm-sh/nvm
• For Windows users: https://github.com/coreybutler/nvm-windows

2. Install node version 18:

   nvm install 18.19.0
   

3. Use that node version:

   nvm use 18.19.0
   

4. Check that Node and npm are set up:

   node -v
   

   npm -v
   

The node version should be 18.19.0 and the npm version should be 10.2.3. If they are not these versions, or if either of those commands cause an error, node has not been installed correctly.

Clone Repository and Install Dependencies

1. Clone the git repository:

   git clone https://github.com/codeforpdx/PASS.git
   

2. Install project dependencies:

   npm install
   

Configuration steps

The current version of PASS currently uses .env file to load environment variables. To set up the environment variables:

1. Navigate to the project's root directory

2. Copy the env.template file into a .env file. With this command:

   cp env.template .env
   

Launching a Development Podserver

PASS can 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.

1. Navigate to the project's root directory

2. Launch the development podserver with:

   npm run podserver
   

This will 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.

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.

3. Open a browser and navigate to http://localhost:3000. You should get a "Community Solid Server" screen. In the "Getting started as a user." section, click on the "Sign up for an account," asking you to set up the server and create an account.

4. You'll be taken to an "Create Account" screen. Create a new Podserver account by inputting an email, password and confirm password in those fields, and then click on the "Register" button at the bottom.

5. You'll be takewn to another "Community Solid Server" page for "Your account." The email login you just registered should be in the "Email/password logins" section at the top.

6. In the "Pods" section on that page, click the "Create pod" link.

7. This will take you to another "Create account" page for the Podserver. Fill in the "Name" field with whatever name for the Pod you wish.

8. Below that, click the radio button for "Use the WebID in the Pod and register it to your account," unless you're testing with an external WebID you already have, in which case, click the "Use an external WebID" radio button and input that external WebID in that field. Once that is all filled in, click the "Create pod" button at the bottom.

9. You'll be take to a screen that has "Your new Pod" and "Your new WebID" and the URLs at which they're located. Note these down for use.

Launching PASS

1. Navigate to the project's root directory

2. Launch PASS with the command:

   npm run dev
   

3. 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.

4. Click the Login button on the home page. You should be redirected to your local pod server if everything has been set up correctly.

⬆️ Back to Top