Realworld App

A full-stack Node.js application built with Angular, and Nest based off of the Realworld OAS.

Table of Contents:

1. Description
2. Prerequisites
3. Deployment
4. Environment Configuration
5. Choosing a Web Framework
6. HTTP2
7. Choosing a Database
8. Testing
9. TypeDocs
10. Logs

🔎 This repo was created with Nx.

📚 Description

This application is template from Sals' NEST REST TYPEORM STARTER which was made to quickly prototype backend applications. Deployed with authentication/authorization, logging, crud features and database persistence out of the box.

🛠️ Prerequisites

Non Docker

• Please make sure to have Node.js (16+) locally by downloading the Javascript runtime via brew, choco, or apt-get.

• Please make sure to have PostgreSQL locally by deploying a web server stack like XAMPP. The control panel can then trigger PostgreSQL to start on localhost. PostgreSQL can be downloaded standalone via brew, choco, or apt-get.

Docker 🐳

• Please make sure to have Docker Desktop operational to quickly compose the required dependencies. Then follow the docker procedure outlined below.

🚀 Deployment

Manual Deployment without Docker

• Clone the repo via git clone https://github.com/msanvarov/nest-angular-realworld-app.

• Download dependencies via npm i or yarn.

• Create a .env file via the cp .env.example .env command and replace the existing environment variable placeholders with valid responses.

• Start the api in development mode by using npm run start (the api will be exposed on http://localhost:3333, and the default ui will be exposed on http://localhost:4200).

Deploying with Docker 🐳

• Execute the following command in-app directory:

# creates and loads the docker container in detached mode with the required configuration
$ docker-compose up -d

• The following command will download dependencies and execute the web application on http://localhost:80 (deployed behind a Nginx reverse proxy).

🔒 Environment Configuration

By default, the application comes with a config module that can read in every environment variable from the .env file.

APP_ENV - the application environment to execute as, either in development or production. Determines the type of logging options to utilize. Options: development or production.

WEBTOKEN_ENCRYPTION_KEY - the key to encrypt/decrypt web tokens with. Make sure to generate a random alphanumeric string for this.

WEBTOKEN_EXPIRATION_TIME - the time in seconds when the web token will expire; by default, it's 2400 seconds which is 40 mins.

DB_TYPE - the type of database connection to use.

DB_USERNAME - username for authenticating against the database.

DB_PASSWORD - password for authenticating against the database, can be left empty if a password is not needed (not safe).

DB_HOST - the endpoint where this database sits (default is localhost but can be set explicitly).

DB_PORT - default ports for different types of database connections.

DB_DATABASE - the actual database name to perform operations on.

🏗 Choosing a Web Framework

This boilerplate comes with Fastify out of the box as it offers performance benefits over Express. But the Express adapter is still accessible on a different branch.

💾 Choosing a Database

By default PostgreSQL is the database of choice but TypeORM supports other database types like SQLite, MySQL/MariaDB, MongoDB, and MSSQL. To use anything other than MYSQL/MariaDB, change the configuration in the .env file, and download the corresponding wrapper library, like SQLite3.

Check https://typeorm.io/ for supported database types.

Remark: For MongoDB, TypeORM is not as feature-rich as Mongoose. Therefore I created another boilerplate for Nest and Mongoose.

🦾 HTTP/2

Luckily, Fastify can enable HTTP2 over either HTTPS (h2) or plaintext (h2c) out of the box. This boilerplate makes use of this on the feat/http2 branch where a self-signed certificate was created for testing this capability. The certificate is located in the certs folder. For production, please use a valid certificate.

The self signed certificate can be generated via OpenSSL:

openssl req -x509 -newkey rsa:4096 -keyout api-key.pem -out api-cert.pem -days 365 -nodes

Remark: Express can be ran with HTTP/2 by employing the spdy library.

✅ Testing

Docker 🐳

# Start the docker container if it's not running
$ docker start nest-rest-typeorm-api

# unit tests
$ docker exec -it nest-rest-typeorm-api npm run test

# test api against postman collection
$ docker exec -it nest-rest-typeorm-api npm run test:postman

Non-Docker

# execute test
$ npm run test

# test api against postman collection
$ npm run test:postman

💡 TypeDocs

The documentation for this boilerplate can be found on Github pages.

The docs can be generated on-demand, by typing npm run typedocs:api:start. This will produce a docs/api folder with the required front-end files and start hosting on localhost.

Remark: The docs for the ui are generated on-demand, by typing npm run typedocs:ui:start. This will produce a docs/ui folder with the required front-end files and start hosting on localhost.

# generate docs for api code
$ npm run typedocs:api:start

📝 Open API

Out of the box, the web app comes with OAS; an open api specification, that is used to describe RESTful APIs. Nest provides a dedicated module to work with it.

The configuration for OAS can be found at this location.

The client lib is generated with OpenAPI Generator to be compatible with the UI application out of the box. The reference OAS yaml file can be found at this location.

✨ TypeORM

TypeORM is an object-relational mapping that acts as an abstraction layer over operations on databases. Please view the documentation for further details.

The configuration for TypeORM can be found in the app module.

🔊 Logs

This boilerplate comes with a Winston module for extensive logging, the configurations for Winston can be found in the app module.

🏗️ Progress

👥 Help

PRs are appreciated, I fully rely on the passion ❤️ of the OS developers.

License

This starter API is MIT licensed.

Author