git clone https://github.com/hazardsoft/nodejs2023Q2-service
git checkout auth
- Install dependencies
- Create .env config
- Run application with Docker
- Run application w/o Docker (optionally)
npm install
Create 2 config files out of .env.example
via copy/paste:
.env
file to be used to local development (setPOSTGRES_HOST
variable tolocalhost
);.env.docker
to be used by Docker (make sure thatPOSTGRES_HOST
is set todatabase-service
).
Docker Compose is used to run application (REST API application and PostgreSQL server will be started). There are 2 modes of running application: development and production. Each mode has distinguishing features described below:
N.B. Application can not be run in both mode simultaneously (in that case port is already allocated
error can be seen in the console), if one mode already started and you want to start another one, please stop already running first.
Development mode is used for local development specifically and has number of distinguising features:
- dedicated Dockerfile-dev file is used to build REST API image (includes dev dependencies from
package.json
) src
andtest
local folders are binded to the REST API container to enable watch mode and provide ability to run tests in the container;- REST API application port is exposed to
localhost
so it can be tested locally (e.g. via Postman or http://localhost/doc Swagger docs); - Logs are enabled for PostgreSQL server;
- PostgreSQL data and logs are stored in dedicated docker volumes (so they can be checked even after containers are stopped/destroyed);
- PostgreSQL server port is exposed to
localhost
so a UI client (e.g. DBeaver) can be used to explore DB data.
start:
docker compose --env-file .env.docker up --build --detach
stop:
docker compose down
Production mode is introduced for CI/CD use primarily and has number of distinguising features:
- REST API service start depends on PostgreSQL service start after successful healthcheck only;
- REST API and PostgreSQL both belong to the same custom network and use that network for communication: REST API is exposed to
localhost
while PostgreSQL not (can be accessed by REST API service only, no other container can communicate with PostgreSQL container); - REST API uses dedicated Dockerfile that does not include any dev dependencies from
package.json
; - No dedicated volumes are used to store data/logs;
- None of local folders are bind mounted (dev watch and tests are not accessible).
start:
docker compose -f docker-compose-prod.yml --env-file .env.docker up --build --detach
stop:
docker compose -f docker-compose-prod.yml down
Normally application should be run with Docker Compose (refer to Running Application with Docker).
If you still need to run application/tests w/o Docker (e.g. for better debug experience), the following steps should be done:
- run
docker compose --env-file .env.docker up database-service --build --detach
command - runs PostgreSQL service only - run
npx prisma migrate deploy
- applies prisma migrations to the database started in p.1 - run
npx prisma generate
- generates Prisma Client - run
npx prisma db seed
- seeds database started in p.1 - run
npm run start:dev
- run
npm run test:auth
- Run Tests
- Application Logs
- Custom Network
- Application Auto Restart
- Database data/logs in Volumes
- Docker Image Size
- Vulnerabilities Check
- Docker Hub
- Database Migrations
- ESLint/Prettier
Run application in development mode. Please refer to Development Mode for more details
Tests can be run either on host or in a container:
- to run tests on host run command
npm run test:auth
in a terminal (as usual); - to run tests in the container :
By default 2 logs files are created:
./logs/combined.log
- contains logs with all levels (except oferror
);./logs/error.log
- contains logs witherror
log level only.
.env.example
has several settings responsible for configuring logs:
LOG_LEVEL
defines log levels (log levels naming and values fully correspond Nest ones); can be array of log levels (e.g.LOG_LEVEL=log,error
) or contain one log level only (e.g.LOG_LEVEL=debug
);LOG_TARGET
defines list of targets to write logs to; can be array of targets (e.g.LOG_TARGET=stdout,file
) or contain one target only (e.g.LOG_TARGET=file
);LOG_LIMIT
defines max log file size in kilobytes (e.g.LOG_LIMIT=20
): once file size limit is reached current log file is closed and a new one is created;LOG_FOLDER
defines folder where all logs will be created.
If application is run in Development Mode docker volume rest-logs
is created and stores all log files created by the application.
Custom network is configured and used if application is run in production mode only! Please refer to Production Mode for more details.
REST API application restarts if changes are introduced into files under src
folder.
Log message File change detected. Starting incremental compilation...
displays in a running docker container under Logs
tab of Docker Desktop (refer to image below).
Watch mode is used if application is run in development mode only! Please refer to Development Mode for more details
PostgreSQL data and logs are stored in corresponding volumes pg-data
and pg-logs
(refer to images below).
These volumes are created/used if application is run in development mode only! Please refer to Development Mode for more details
REST API is built into two different Docker images:
- development (includes dev deps, built from Dockerfile-dev)
- production (w/o dev deps, built from Dockerfile, published to Docker Hub)
Both images are under 500mb due to use of multi-stage builds (refer to images below).
Docker Scout is used to scan images for vulnerabilities
To run security checks use the following NPM scripts:
npm run vulns:rest
npm run vulns:db
Both REST API and PostgreSQL docker images are published to Docker Hub (refer to image below):
Prisma Migrate is used to apply migrations to a database and seeding right after REST API application starts (both in development and production modes).
The following commands are called when container starts:
npx prisma migrate deploy
- Prisma applies migrations stored inprisma/migrations
folder to a running database;npx prisma db seed
- Prisma runsprisma:seed
command defined inpackage.json
to create defaultFavorite
entity.
npm run lint
npm run format