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 Solid Server

PASS can connect to any solid-spec compliant pod server. However, for testing, it's recommended that you run a server locally for development and testing. PASS provides tools to make this easy to do.

1. Navigate to the project's root directory

2. Launch the development server with:

   npm run podserver
   

This will launch a local Solid server where you could create pods. 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 taken 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 taken to a screen that has "Your new Pod" and "Your new WebID" and the URLs at which they're located. Note these down to use for your login to the PASS web site.

   

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.

   

4. Once you visit that url, click the Login button on the home page to your local Pod server to finish login, using the WebID you just authorized from above, click the "Remember this client" checkbox, and click the "Authorize" buton. if everything has been set up right, you should be logged into your local Pod server and logged into your local PASS page.

   

Launching PASS with Local Solid Server

To ease development, the library concurrently has been included as part of our development environment. As such, you would only need to run:

  npm run start

To start both PASS and the local Solid Server if you wish to not open separate terminal windows for running PASS and the local Solid server separately as shown from the instructions in previous sections.

⬆️ Back to Top