finder

Repo for a project for University. WyeWorks is the client, students implement it.

Table of Contents

• Requirements
• Setup
• Linting
• Tests
• Coverage
• CI
• Deployment
• API Endpoint Documentation

Requirements

Project presentation, which includes functional and non-functional requirements, can be found here.

Setup

Homebrew & dependencies

Homebrew can be used for installing packages and system dependencies locally. Instructions can be found here.

Note: Homebrew instructions above are for macOS. It can also be used for Linux following these instructions. For Windows, there are a few alternatives like Ninite or Chocolatey.

Postgres

Postgres will be used as the relational database. Install it using Homebrew by running:

$ brew install postgresql

Ruby

This project needs ruby to be installed. The right version of Ruby is stored in the .ruby-version file on the finder/api folder. Currently, this application uses Ruby v3.2.2.

To manage different versions of ruby, different ruby version managers can be used:

• chruby
• rbenv
• rvm

Please follow their instructions on how to install them, and how to install the ruby version required by the app.

Gems

Install gems for the rails app:

$ cd finder/api
$ bundle install

Rails

Install the rails version used on the Gemfile.lock:

$ sudo gem install rails -v VER.SI.ON

Currently, this application uses Rails v7.0.7.2.

Frontend

React (v18) and Tailwind are used for the Frontend application, all together within a Next.js framework (v13).

Make sure to have the latest npm version (v10). Then run:

$ cd finder/client
$ npm install
$ npm run build

Replace values from .env.local.example file with the correct ones. For example, for running the stack locally, the following configuration can be used:

RAILS_API_URL=http://0.0.0.0:3000
NEXT_PUBLIC_RAILS_API_URL=http://127.0.0.1:3000
NEXTAUTH_SECRET=sd;fkjsfda;pjh
NEXTAUTH_URL=http://localhost:3333

Then rename the file to .env.local.

Database

Setup local db and populate it with data:

$ cd finder/api
$ bundle exec rails db:setup

This last command does: db:create db:schema:load db:seed. Last one, db:seed is the one that populates the database will subjects and careers data from a seed file.

Another option would be to run:

$ cd finder/api
$ bundle exec rails db:create db:migrate db:seed

Users, groups, and test study sessions can also be created with the following commands:

$ cd finder/api
$ bundle exec rake db:seed:resources

Start App Locally

Run api (BE) and client (FE) separately. Since both Rails and Next.js use 3000 as the default port number, one of them had to be moved to another one. Backend uses the port 3000, and frontend the 3333.

$ cd finder/api
$ bundle exec rails s

$ cd finder/client
$ npm run dev

Open the browser and navigate to localhost:3333. Congratulations, you have successfully set up your machine for development!

Linting

rubocop is used in the Rails application for static code analysis:

$ cd finder/api
$ rubocop

ESLint for the Next.js application:

$ cd finder/client
$ npm run lint

Note: this last one runs automatically with a pre-commit hook.

Tests

Backend testing with RSpec. Frontend with Jest and React Testing Library.

$ cd finder/api
$ bundle exec rspec

$ cd finder/client
$ npm run test

Coverage

Rails application uses simplecov gem for generating coverage from the rspec tests. After running those tests, an html file gets generated and can be accessed from the local browser on: file:///{path_to_application}/finder/api/coverage/index.html

Frontend coverage html file can be generated by running:

$ cd finder/client
$ npm run coverage

A new coverage folder within the client one will be generated, containing the html file: file:///{path_to_application}/finder/client/coverage/Icov-report/index.html

CI

Github actions for the two separate applications are configured in .github/workflows/. /next.yml runs the Jest tests. /rails.yml runs rubocop and RSpec tests.

Deployment

Frontend application is deployed using Vercel. Backend using Render.

finder has two separate environments: Production and QA.

• Production BE
• Production FE
• QA BE
• QA FE

For configuration, the following Environment Variables must be set:

Backend

• DB_HOST: host of the database server
• DB_PORT: port where the db server is exposed
• DB_NAME: name of the database
• DB_USER: the user the app should use to log into the DB
• DB_PASSWORD: the password to be used for authentication against the DB
• RAILS_MASTER_KEY: the key used to decrypt the configuration files
• SECRET_KEY_BASE: key to be used as salt for JWT token generation

Frontend

• RAILS_API_URL: URL of the backemnd API deployment
• NEXT_PUBLIC_RAILS_API_URL: same as RAILS_API_URL but visible from client side
• NEXTAUTH_SECRET: secret to be used as salt for next auth
• NEXTAUTH_URL: URL of the next auth server

API Endpoint Documentation

All backend endpoints are detailed here. Includes information about the path, parameters and body for each request, and response examples.