skal-chin / homeworktracker

StarterApp

Description

A starter app with Postgres, NestJS, and React

Cloning the project

IMPORTANT Windows users should setup WSL first before cloning. See WSL_SETUP.md This app is designed to used as a starting point for another application so you will want to clone the project into a folder that matches your app. Run

$ git clone [email protected]:dittonjs/NestStarterApp.git <YourAppName>

a Replace your app name with the name of your app, for example

$ git clone [email protected]:dittonjs/NestStarterApp.git SpyChat

Next, go create a remote repository in github (or gitlab, or bitbucket, it doesn't matter) for your new application.

Finally, run

$ bash ./bin/setup_new_project.sh

and follow the prompts. This script will link the repo to your new repo while maintaining a reference to the starter app repo. This way, if we make changes to the starter app repo, you can still get those changes.

Pulling Updates from Starter App

To retrieve changes from the starter app run

$ git pull upstream main

Prerequisites

VSCode

I know there are bunch of editors but trust me, VS Code will make your life easier, mostly becuase it is what I use and if you have issues I can help you. If you use something else IT WILL BE YOUR RESPONSIBILITY TO MAKE SURE IT IS CONFIGURED PROPERLY.

Look here for information about which extensions and settings we will use.

WSL

If you are on Windows you will need to install WSL2 you must be on windows 10 or higher. You can find the instructions on how to set this up here.

asdf-vm

Tool versions are managed using asdf-vm. You will need to have asdf-vm installed first. You can install it by following the instructions here.

Setup

Make sure your have navigated to the project directory in your terminal.

Tool versions

Install the tool versions by running

$ asdf install

Install yarn

We will use yarn instead of npm for package managment. To install yarn run

$ npm install -g yarn

.env

Create a file in the root called .env and copy the contents of .env.example.

Make sure you create a new file instead of renaming the .env.example file.

In your new .env file update the values for each key as you would like

Dependencies

To install the both server and client dependencies run

$ yarn # this is same thing as `yarn install`

Notice that the client folder has its own package.json file and its own node_modules. If you add dependencies for the client make sure to cd into the client directory before doing yarn add

Database

This application uses Postgres. To setup the database run

$ yarn db:setup

This will create the database, run the migrations, and run the seeds for you.

Migrations

Any time you want make changes to your database schema you will need to generate a migration file

yarn db:migration:generate AddContextToRoles # replace this name with a name that describes your migration

Open that migration file and make the changes. Then, when you are ready

$ yarn db:migrate

will run any pending migrations.

If a team member adds a migrations you will need to run the migrate command to make the changes to your local database as well.

Seeds

Seeds allow you to pre-populate your database with data. By default this application prepopulates the Roles and the Admin User into your database.

If you make changes to the seeds file at server/database/seeds.ts the make sure that, in the event seeds are run multiple times, you don't end up with duplicate data.

To run the seeds

$ yarn db:seed

SSL

Only do this step if you intend on developing your app in an environment where you need SSL (like canvas or other embedded platforms).

In your .env set

USE_SSL=true

Create a ssl key and certificate and place them in the root directory

$ openssl req -x509 -newkey rsa:4096 -keyout private-key.pem -out public-cert.pem -sha256 -nodes

Enter US for the country code. Where this key will only be used for development you can leave all of the rest of information blank.

Running the app

To start the server run

$ yarn start:dev

To start the client run

$ yarn client:watch

Test

WORK IN PROGRESS

# unit tests
$ yarn test

# e2e tests
$ yarn test:e2e

# test coverage
$ yarn test:cov

Setup Heroku

We will deploy all our projects to Heroku. Heroku is a cloud platform that is easy and free to use. You will only need to run these step once for each computer you are working on this semester.

Create an account

On heroku.com create an account.

Install Heroku CLI

If you don't have the heroku CLI installed you can install it by running. You should only need to do this once on each computer you are working on.

$ curl https://cli-assets.heroku.com/install.sh | sh

Login to CLI

To log into the CLI run

$ heroku login

and follow the prompts. After a while, you maybe be prompted to login again which is fine.

Deploy Setup

Follow these steps to setup your app for deploy, you should only have to do this once per application

Create app in heroku

1. Go to your heroku dashboard and create a new application.

2. Once your app has been created you will need to enable the Postgres addon. Select the Resources tab and search for Heroku Postgres addon.

3. On the screen that pops up make sure Hobby Dev is selected (that is the free option) and click the submit order button.

4. Click on the Settings tab, select the Reveal Config Vars button, and verify you have an entry for DATABASE_URL.

Setup config vars

You will need to add entries in Heroku for each of the production config vars in the .env file.

To do this go the Settings tab in your app on heroku and click Reveal Config Vars. Fill out the key and value for each entry.

DO NOT MANUALLY SET THE PORT, USE_SSL, NODE_ENV, OR DATABASE_URL VARS. These will be managed for you by Heroku

You should generate new values for the ENCRYPTION_KEY, REFRESH_ENCRYPTION_KEY, and ADMIN_PASSWORD vars. I recommend using a real email address for your ADMIN_EMAIL.

All vars should be named the exact same as they are in the .env file.

Link to Heroku

You publish to Heroku using git. Run the following command to add the heroku remote

$ heroku git:remote -a <your app name>

If your app name in Heroku was spy-chat then you would run

$ heroku git:remote -a spy-chat

Deploying

We finally made it! To deploy your app to Heroku run

$ git push heroku main

and thats it!