Intercambio ltd.

This project is built on Nestjs

Contents

• Deploy Locally
  • Prerequisite
  • Build app
  • Optional - Create docker-compose.override.yml
  • Run a project
  • Check if it works
  • Database installion
  • Obtain a JWT token
  • Mailer
• Code Quality
  • Static Analysis tools and linters
    • Prerequisites
    • Usage
    • Tests
    • Usage
• Working with Git
  • Requirements
  • Why having an issue ID is important
  • Configure git username and email
  • Git hooks
  • Git flow
  • Remove your remote branches

Deploy Locally

Prerequisite

Project uses Docker, before continue, make sure Docker is installed on you host machine.

Once docker is installed please implement all post install steps

Build app

Run the following command on your host machine in root directory to build the projects:

make build

# Configure git prepush
make setup

This command will download, build all the needed images and run containers, including:

• Node
• Database
• Test Database - only for dev needs, used during tests running instead of the original database.
• SFTP Server - only for dev needs as an analogue for the prod SFTP servers on AWS
• Mailer - only for dev needs, SMTP server which catches any message sent to it to display in a web interface

Database will be created and populated with demo fixtures automatically.

[Optional] Create docker-compose.override.yml

If you want to specify ports, please create docker-compose.override.yml e.g:

version: "3.9"

services:
  db:
    ports:
      -   target: 3306
          published: 5333
          protocol: tcp

Run a project

Run the following command on your host machine:

make run

The command will start all services.

Check if it works

• http://localhost:3000

Database installation

Within the docker configuration two databases are setup, for a development and tests.

Development Database

The seeders for the development will run upon running

make run

However if you would like to reinstall the database, run:

make db-reinstall

Test Database

The seeders that the test database require are not the same as the development database. Thus, in order to prepare the test database for appropriate testing you must run:

make db-test-install

Obtain a JWT token

Swagger - Development

After running make run open http://localhost:3000/ in any web browser, access the jwt section inside the module and supply a valid user email and password. The resulting status will be 201 and the response data will contain the user_id, expiration in seconds, token and refresh token.

Docker troubleshooting

At first check if Docker has been installed correctly, and you have implemented all post install steps. And please make sure, that current user has been added into the 'docker' group and port forwarding in your OS has been enabled ($ sysctl net.ipv4.ip_forward).

Please check if you have docker installed as a service and if it is running.

Didn't help? Have you tried turning it off and on again? Like these:

docker-compose down
docker system prune -f
docker-compose build --no-cache
docker-compose up -d --force-recreate

To debug you may run shell from the container:

docker exec -it XXX sh

To get the list of images:

docker container ls [-a]
# or
docker ps [-a]

Both commands show all containers. Without '-a' key you may see only running containers.

To remove all unused images:

docker system prune

To display logs of container XXX:

docker logs XXX

TODO: add when Mailer will be implemented

Mailer

Locally we have a mailer container, a super simple SMTP server which catches any message sent to it to display in a web interface.

By default, Mailer Web interface can be accessed through http://localhost:1080.

Code Quality

Static Analysis tools and linters

To run all code quality checkers and tests by one command, run

make analyse

To run all linters by one command, run

make lint-check

Tests

Usage

First, you should create a test database with all tables (you can use this command to re-create test db as well):

make db-test-install

To run all tests, run

make tests

Working with Git

The project uses git flow branching model. If you are not familiar with it, please read this article http://nvie.com/posts/a-successful-git-branching-model/

Requirements

• Feature branch MUST contain an issue ID form JIRA, e.g. feature/EP-??, -x-y-z is optional part.

• Bug fix branch MUST contain an issue ID from JIRA, e.g. bugfix/EP-?? if it requires many changes

• Small bug fixes, related to one feature (NST-111), can be grouped into one branch: bugfix/EP-??. For each fixed bug add a separate commit with corresponded issue ID at the beginning of the message.

• Commit message MUST contain an issue ID at the beginning of the message, e.g.

• Commit message SHOULD have a detailed message about what was done.

How to write good commit messages? Read this article http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Why having an issue ID is important

Bitbucket has a deep integration with JIRA, and all issue IDs are clickable and are links to corresponded tasks in JIRA. At the same time, there is a section in JIRA ticket that displays existing Branches and commits for this task.

Configure git username and email

• git config --global user.email "your.name@itransition.com"
• git config --global user.name "Surname, Name"

Git hooks

pre-push hook will check that your code is not broken before it is pushed to the remote repository.

However, there are some cases where such checks should be skipped, e.g.:

• When you're rebasing your branch and want to push to origin
• When you remove your branch from the remote repository

In such cases, it's possible to turn off git hooks temporarily using --no-verify option.

• git push origin HEAD --no-verify --force-with-lease - pushes a current branch to origin without executing git hooks
• git push origin --delete --no-verify feature/EP-XXX - removes a remote branch without executing git hooks

Git flow

When you have more than 1 commit in your feature branch, they SHOULD be squashed before merging to main locally.

The typical git workflow looks like:

# start a new feature branch from main
git checkout -b feature/EP-1

# commit your changes
git commit -m "EP-1 Detailed message"

# create pull request

# Before merging to main, rebase and squash all commits into one (should be done by default)
# except case when you have a reason to leave separate commits in the history
git checkout main
git pull --rebase
git checkout feature/EP-1
git rebase main -i

# push squashed branch to remote
git push origin --force-with-lease feature/EP-1

# merge with --no-ff in case you want to leave a merge commit and your reasonable commits in a history as a parallel branch
git checkout main
git merge feature/EP-1 --no-ff

git push origin main # at this moment, the status of PR will be automatically changes to "Merged"

# (!) and finally remove your branch
git push origin --delete feature/EP-1
git branch -d feature/EP-1

Option --no-ff creates additional merge commit during merging process. Git history will have 2 new commits - your origin one and merge commit.

(!) Always rebase your branch on fresh main before merging your PR.

Remove your remote branches

Old branches pollute the repository. Remove branches when they are merged to main.