-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'dev' into bugfix/server-crash-token-not-in-db
- Loading branch information
Showing
18 changed files
with
3,465 additions
and
3,015 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,48 @@ | ||
| # Chingu Dashboard | ||
|
|
||
| <!--[](https://opencollective.com/nest#backer) | ||
| [](https://opencollective.com/nest#sponsor)--> | ||
|  | ||
|  | ||
|  | ||
|
|
||
|  | ||
|  | ||
|  | ||
|
|
||
| ## Description | ||
|
|
||
| This is the Chingu Dashboard backend project. Be sure to set your .env [environment variables files](#envfiles) | ||
| This is the Chingu Dashboard backend project. | ||
| You can run the project locally or using Docker. | ||
| Once you have cloned the repo locally, be sure to set your .env [environment variables files](#envfiles) | ||
|
|
||
| ## <a name="envfiles">Environment variables</a> | ||
|
|
||
| - if using the docker databases, and an external terminal, use these DATABASE_URL | ||
| - if using the docker databases, and an external terminal, use these DATABASE_URL | ||
|
|
||
| ```bash | ||
| # .env | ||
| DATABASE_URL=postgresql://chingu:chingu@localhost:5433/dashboard?schema=public | ||
| # .env.test | ||
| DATABASE_URL=postgresql://chingu:chingu@localhost:5434/dashboard?schema=public | ||
| ``` | ||
|
|
||
|
|
||
| ```bash | ||
| # .env | ||
| DATABASE_URL={your database url} | ||
| PORT=8000 | ||
|
|
||
| JWT_SECRET= | ||
| AT_SECRET= | ||
| RT_SECRET= | ||
| JWT_SECRET={can be any string} | ||
| AT_SECRET={can be any string} | ||
| RT_SECRET={can be any string} | ||
| BCRYPT_HASHING_ROUNDS=10 | ||
|
|
||
| MJ_APIKEY_PRIVATE= | ||
| MJ_APIKEY_PUBLIC= | ||
| MJ_APIKEY_PRIVATE={check Important Resources page} | ||
| MJ_APIKEY_PUBLIC={check Important Resources page} | ||
|
|
||
| NODE_ENV=development | ||
|
|
||
| FRONTEND_URL=https://chingu-dashboard-git-dev-chingu-dashboard.vercel.app/ | ||
|
|
||
| DISCORD_CLIENT_ID= | ||
| DISCORD_CLIENT_SECRET= | ||
| DISCORD_CLIENT_ID={check Important Resources page} | ||
| DISCORD_CLIENT_SECRET={check Important Resources page} | ||
| DISCORD_CALLBACK_URL=http://localhost:8000/api/v1/auth/discord/redirect | ||
|
|
||
| # .env.test | ||
|
|
@@ -48,16 +52,18 @@ NODE_ENV=test | |
|
|
||
| ## Installation | ||
|
|
||
| To install all the project's dependencies run: | ||
| If you don't have yarn installed, make sure to install it first. Some useful steps are available in the [official Yarn documentation](https://yarnpkg.com/getting-started/install). | ||
|
|
||
| To install all the project's dependencies run the following command in the project root: | ||
|
|
||
| ```bash | ||
| $ yarn install | ||
| ``` | ||
|
|
||
|
|
||
| ## <a name="prismaStudio">Prisma</a> **IMPORTANT: If you're using the docker setup in this project, go to the docker section** | ||
|
|
||
| To prepare the DB | ||
|
|
||
| ```bash | ||
| # migrate db schema | ||
| $ yarn migrate | ||
|
|
@@ -68,6 +74,7 @@ $ yarn seed | |
| # run Prisma Studio | ||
| $ yarn studio | ||
| ``` | ||
|
|
||
| > [!TIP] | ||
| > It is recommended to use `db push` to [prototype your schema](https://www.prisma.io/docs/orm/prisma-migrate/workflows/prototyping-your-schema) | ||
|
|
@@ -91,7 +98,7 @@ $ yarn start:prod | |
| ```bash | ||
| # all tests (unit and e2e for now) | ||
| $ yarn test | ||
| $ yarn test | ||
|
|
||
| # unit tests | ||
| $ yarn test:unit | ||
|
|
@@ -106,10 +113,11 @@ $ yarn test:int | |
| $ yarn test:cov | ||
| ``` | ||
|
|
||
| If using the docker terminal the commands would be | ||
| If using the docker terminal the commands would be | ||
|
|
||
| ```bash | ||
| # all tests (unit and e2e for now) | ||
| $ yarn test:docker | ||
| $ yarn test:docker | ||
|
|
||
| # unit tests | ||
| $ yarn test:unit:docker | ||
|
|
@@ -124,38 +132,43 @@ $ yarn test:int:docker | |
| $ yarn test:cov:docker | ||
| ``` | ||
|
|
||
| ## Docker | ||
| ## Docker | ||
|
|
||
| By using Docker you can: spin up Postgres, the API & PGAdmin, as well as run prisma Studio and even tests. | ||
| Start by installing Docker if you don't have it already (it may require a machine restart in order to finalize installation). | ||
|
|
||
| ### Running the project in Docker | ||
|
|
||
| With Docker open, from the project's root you can run Docker in dev or testing mode: | ||
| Open the Docker app and from the project's root you can run Docker in dev or testing mode using commands below: | ||
|
|
||
| ```bash | ||
| # spin up dev Docker services (API, PGAdmin, Postgres DB) | ||
| $ yarn docker | ||
| ``` | ||
|
|
||
| Docker will run in detached mode, meaning it's effectively running in the background, however, you will need to use the various scripts inside the docker cli. | ||
|
|
||
| Once the services are spun up, go to your docker desktop and go to chingu-dashboard-be_api container and click into it. | ||
| Once the services are spun up, go to your docker desktop, chingu-dashboard-be container, click into it and then locate the chingu-dashboard-be_api container. | ||
|
|
||
| After, click on the CLI to into the terminal inside the container. | ||
| Using the container actions, select 'Open in terminal'. | ||
|
|
||
| From here, type all the commands [above](#prismaStudio). | ||
|
|
||
| ## PG Admin | ||
|
|
||
| http://localhost:4000/ | ||
|
|
||
| Login with | ||
| Login with | ||
|
|
||
| ``` | ||
| [email protected] | ||
| chingu5432 | ||
| ``` | ||
|
|
||
| Right click Servers -> Register -> Server... | ||
|
|
||
| dev database | ||
|
|
||
| ``` | ||
| hostname: postgres | ||
| port: 5433 | ||
|
|
@@ -165,6 +178,7 @@ password: chingu | |
| ``` | ||
|
|
||
| test database | ||
|
|
||
| ``` | ||
| hostname: postgres-test | ||
| port: 5434 | ||
|
|
@@ -175,14 +189,17 @@ password: chingu | |
|
|
||
| Having spun up your Docker services and migrated + seeded your DB your services will be running on the following default ports: | ||
|
|
||
| - API: `8000` | ||
| - Postgres: `5433` | ||
| - PGAdmin: `4000` | ||
| - Prisma Studio: `5555` | ||
| - API: `8000` | ||
| - Postgres: `5433` | ||
| - PGAdmin: `4000` | ||
| - Prisma Studio: `5555` | ||
|
|
||
| If you want to manually check that the API is receiving incoming requests, you can perform a GET request on the health endpoint using a tool like Postman (or another tool of your choice). | ||
|
|
||
| ### <a name="tearDown">Tearing down Docker services</a> | ||
|
|
||
| To stop and tear down the Docker services: | ||
|
|
||
| ```bash | ||
| # tear down all Docker services but retain volumes | ||
| $ yarn docker:down | ||
|
|
@@ -192,67 +209,84 @@ $ yarn docker:clean | |
| ``` | ||
|
|
||
| ## Custom Pipes | ||
|
|
||
| ### FormInputValidationPipe | ||
| For use with form responses, this pipe validates that the responses or response (array) values include a questionId and at least one input value of any type. | ||
|
|
||
| For use with form responses, this pipe validates that the responses or response (array) values include a questionId and at least one input value of any type. | ||
|
|
||
| Example: `@Body(new FormInputValidationPipe())` | ||
|
|
||
| ### VoyageTeamMemberValidationPipe | ||
| It checks the voyageTeamMemberId in the request body and validates if the logged in user belongs to that team. | ||
|
|
||
| It checks the voyageTeamMemberId in the request body and validates if the logged in user belongs to that team. | ||
|
|
||
| Example: `@Body(VoyageTeamMemberValidationPipe)` | ||
|
|
||
| ## Custom Decorators | ||
| ## Custom Decorators | ||
|
|
||
| ### @Public() | ||
|
|
||
| Marks the route as public, bypassing the JWT auth guard (`jwtAuthGuard`) | ||
|
|
||
| Examples: <br/> | ||
| `@Public()` | ||
| `@Public()` | ||
|
|
||
| ### @Unverified() | ||
|
|
||
| Marks the route as accessible to users that have not verified thier account by email | ||
|
|
||
| ### @CheckAbilities() | ||
| This accepts 2 arguments - | ||
|
|
||
| This accepts 2 arguments - | ||
| <br/> | ||
| action: Manage, Create, Read, Update, Delete, etc | ||
| action: Manage, Create, Read, Update, Delete, etc | ||
| <br/> | ||
| subject: 'User', 'Voyage' - these are prisma models | ||
| subject: 'User', 'Voyage' - these are prisma models | ||
|
|
||
| - Actions, and abilites are defined in the CASL factory `src/ability/ability.factory/ability.factory.ts`, | ||
| where the subjects are defined in `prisma-generated-types.ts` | ||
| - Manage, and 'all' are wildcards | ||
| - They also accept arrays like `action: [Action.Read, Action.Update]` | ||
| - Actions, and abilites are defined in the CASL factory `src/ability/ability.factory/ability.factory.ts`, | ||
| where the subjects are defined in `prisma-generated-types.ts` | ||
| - Manage, and 'all' are wildcards | ||
| - They also accept arrays like `action: [Action.Read, Action.Update]` | ||
|
|
||
| Examples: <br/> | ||
| `@CheckAbilities({ action: Action.Manage, subject: "all" })` - when a route is marked with this, | ||
| `@CheckAbilities({ action: Action.Manage, subject: "all" })` - when a route is marked with this, | ||
| only users with the ability to manage 'all' subjects are allowed to access to route, | ||
| otherwise, a 403 forbidden error is returned. | ||
|
|
||
| `@CheckAbilities({ action: Action.Read, subject: "VoyageTeam" })` - users with Read ability for `VoyageTeam` subject can access this route. | ||
|
|
||
| ## Custom Exception Filter | ||
|
|
||
| Note: A try-catch block is not required to catch these exceptions | ||
|
|
||
| ### Prisma Client exception Filter (`prisma-client-exception.filter.ts`) | ||
|
|
||
| This filter catches all prisma generated exceptions with type `PrismaClientKnownRequestError` and handle them | ||
|
|
||
| ### CASL Forbidden Exception Filter | ||
|
|
||
| This filter catches all `ForbiddenError` from `@casl/ability` | ||
|
|
||
| ## Global Guards | ||
|
|
||
| These guards are applied to every route in the app | ||
|
|
||
| ### JWT Auth Guard (JwtAuthGuard) - `jwt-auth.guard.ts` | ||
|
|
||
| This guard checks user access based on the passport strategy 'jwt-at', which extracts cookies from the request body, validates the user in the database and attaches additional user information in req.user | ||
| It also checks if the `@public()` is applied to the route, if yes, user access check is bypassed | ||
|
|
||
| ### CASL Abilities Guard (AbilitiesGuard)- `abilities.guard.ts` | ||
|
|
||
| This guard defines and checks required permissions to access the route, it checks if the user has the required permission based on user roles. | ||
| Permissions based on roles are defined in the CASL ability factory (`ability.factory.ts`) | ||
|
|
||
| ## Guards | ||
|
|
||
| ### JWT Refresh Token Guard (JwtRefreshAuthGuard) - `jwt-rt-auth.guard.ts` | ||
|
|
||
| This guard is only used for the refresh access token route, `/refresh`, using passport 'jwt-refresh' strategy | ||
|
|
||
| ### Local Auth guard (LocalAuthGuard) - `local-auth.guard.ts` | ||
|
|
||
| This guard is only used for the `/login` route, using the passport 'local' strategy | ||
Oops, something went wrong.