NorseBooks

The NorseBooks project seeks to provide Luther College students a place to buy and sell textbooks to each other.

Table of Contents

• Prerequisites
• Cloning the Project
• Local Deployment
• Testing
• Frontend
• Backend
• Scripts
• Database
• Deployment
• Coverage
• Documentation
• Error Pages
• GitHub Actions
• License

Prerequisites

• Node.js 14.17.4 and NPM 6.14.14
• Python 3.9
• The Heroku Command Line Interface
• PostgreSQL
• TypeScript 4.3.5
• Nest 8.0.0
• Angular 12.0.1
• Angular Material 12.1.4

Cloning the Project

$ git clone https://github.com/NorseBooks/NorseBooks.git

Local Deployment

Build the application using NPM:

# build both the frontend and backend
$ npm run build

# build only the frontend
$ npm run build:frontend

# build only the backend
$ npm run build:backend

The application can be run locally with the Heroku CLI:

$ heroku local web

After the local deployment, the built application can be accessed at localhost:3000.

Testing

We primarily use Jest for automated testing. The tests can be run using NPM:

$ npm run test

Frontend

For frontend, we are using Angular with Material.

Backend

Our backend uses Nest to expose API endpoints for the frontend to access.

Scripts

The repository contains a number of Python scripts found in the scripts directory. Scripts can be called directly or using one of either a bash or batch script for convenience.

Bash:

script.sh [script name] [script arguments...]

Batch:

script [script name] [script arguments...]

Environment Variables

The env.py script provides useful functions for acquiring variables from the environment and from .env files. It is not meant to be invoked directly, but rather to be used from other scripts.

Admin

The admin.py script can be used to give and revoke a user's admin privileges, and to list the current admins. Run with the -h flag for usage help.

Backup

The backup.py script is used to create backups of the database in JSON format. Run with the -h flag for usage help.

Database

We are using a PostgreSQL database, which is accessible from the application itself and via the Heroku CLI.

Deployment

The application is deployed to Heroku. It can be found at nb-2.herokuapp.com.

Coverage

The coverage numbers are shown above. A more detailed coverage report is hosted at norsebooks.github.io/coverage. The coverage report repository exists here. Coverage reports are generated automatically when the tests run.

Documentation

The TypeDoc package is used to generate the project code documentation. It includes annotations for nearly every significant function, class, etc. Documentation can be generated manually with:

$ npm run document

The documentation is hosted at norsebooks.github.io/docs. The documentation repository exists here. The documentation is generated automatically when the tests run.

Error Pages

The error pages are a fallback to account for scenarios in which the application goes down. If the application experiences a fatal error and crashes, the error page will display. If the application is set to maintenance mode in the Heroku control panel, the maintenance page will display. The error pages repository exists here.

GitHub Actions

GitHub Actions runs jobs automatically on any push or pull request to the main and dev branches. This includes running our automated tests, as well as generating coverage reports and documentation, which are pushed to their respective repositories.

License

MIT License