SLU Open Project

This is an open source project management platform for distributed manufacturing, processing, and toolshops within an organization. It was specifically designed for the Saint Louis University Center for Additive Manufacturing, but can be adapted for other organizations.

See the Development documentation for more information and conventions on using and developing this codebase.

Installation & Quickstart

1. Install node.js

2. Install Postgres (or have access to a connection string) and start local server

3. Install yarn (If using Windows machine, use Command Prompt)

npm install --global yarn

4. Clone the repository

git clone https://github.com/oss-slu/core_desk.git

5. Set up environment variables

DATABASE_URL="postgresql://USER:PASSWORD@localhost:5432/YOUR_DATABASE_NAME" (start a local postgres server and put that here)
JWT_SECRET=(random string)
BASE_URL=http://localhost:5173
SERVER_URL=(a globally accessible url, e.g. a tunnel. Ngrok, Bore, and Cloudflare Tunnels are good software options)
SENTRY_AUTH_TOKEN=(Sentry.io auth token)
AWS_REGION=nyc3
AWS_BUCKET=open-project
AWS_ENDPOINT=https://nyc3.digitaloceanspaces.com
PROJECT_NAME=dev-(your first name)
AWS_ACCESS_KEY_ID=(get api key from tech lead or provide your own)
AWS_SECRET_ACCESS_KEY=(get api key from tech lead or provide your own)

6. Install dependencies

cd open-project
yarn

cd app
yarn && yarn build

cd api
yarn

7. Start the development server

cd api
yarn dev

8. Start the react app

cd app
yarn start

9. Open your browser to http://localhost:5173 to view the app

10. To authenticate/log in, we typically use the SLU OKTA log in system, but that is a pain to connect in your local environment, so we have a workaround utility

In the /api folder, run

yarn okta

If this is your first time logging in, allow it to create a new user for you. Once finished, it will give you a line of javascript. Copy/paste that into the browser's console, and that will log you in without having to go through the typical auth flow.

11. Migrate prisma database with local postgres server.

Install Prisma Client

yarn add @prisma/client
yarn add -D prisma

Generate Prisma Client

yarn prisma generate

Apply migrations

yarn prisma migrate dev

12. If you need to access the database (not necessary for initial setup), open Prisma Studio

Run the following in your terminal (Command Prompt for Windows) to open the database

yarn prisma studio

Testing

To run the tests, docker and docker-compose are required.

Install Docker for Windows or Docker for Mac

1. Start Docker Desktop Open Docker Desktop and wait for the app to start completely.

2. Start database from ./api folder (Only run if on Windows computer using Command Prompt. This step is not necessary if on Mac.)

cd api
docker-compose up -d

3. Run the tests from ./api folder

Mac:

cd api
yarn test

Windows:

yarn test

4. To clean up

docker-compose down -v

End-to-End (E2E) tests

Notes:

• Requires Docker and Docker Compose. The compose stack brings up Postgres, MinIO (S3), the API (serving the app), and a Cypress runner.
• Artifacts (videos/screenshots) are saved under e2e/cypress/.
• On Windows, run the following commands with Git Bash or WSL through VS Code.

On Windows from Git Bash in VS Code, you need to convert the /api-entrypoint.sh file to Unix line endings:

cd e2e/docker
dos2unix api-entrypoint.sh

If you are not using VS Code, be sure to have dos2unix installed.

Quick, isolated runs use Docker (recommended) from the root folder:

• Run once: npm run test:e2e
• Watch mode: npm run test:e2e:watch
• Clean up: npm run down:e2e

Local development runner (without Docker):

• Install concurrently if not already installed with npm i -D concurrently - Documentation
• Start the stack in one terminal: npm run dev:stack
• In another terminal, open Cypress: npm --workspace e2e run cy:open
• Headless run locally: npm --workspace e2e run cy:run

Tip: The Cypress base URL defaults to http://localhost:5173 but can be overridden via BASE_URL.