Kampong Backend Service

Backend web service in TypeScript, NodeJS, Express, and PostgreSQL for Project Kampong.

Quick Start

Global dependencies

Latest version of the app has been tested to run on:

- Node v14.16.1
- Yarn v1.22.10
- PostgreSQL 13.2

Package manager

Yarn is the recommended package manager for Project Kampong API. Install yarn here.

Setting up

Install project dependencies

On the command line in the project root directory:

yarn install

Set up config variables

1. In the file config/config.env.env, duplicate the file and rename it to config/config.env.

2. Fill in all credentials required in the new file. See section below to fill in database credentials.

Database setup

Create a new PostgreSQL database instance

The 2 suggested ways of setting up PostgreSQL for the app is shown below. The main difference is the use of Docker to host the database instance.

NOTE: Skip this step if you already have a PostgreSQL database to connect to.

Setting up database (without Docker)

Refer to this guide on creating a PostgreSQL database locally.

Setting up database (with Docker)

Run Docker on your machine, then run the following commands:

docker container run --name kampong-db -e POSTGRES_PASSWORD=kampong -e POSTGRES_USER=kampong-admin -p 5432:5432 -d postgres
docker exec -it kampong-db psql -h localhost -U kampong-admin -c 'CREATE DATABASE kamponglocal;'

Connect PostgreSQL database to the Project Kampong web server

Under config/config.env, fill in PG_USER, PG_HOST, PG_NAME, PG_PORT, PG_PASSWORD with your PostgreSQL database credentials.

For db setup with Docker above, your credentials will be:

PG_USER=kampong-admin
PG_HOST=localhost
PG_NAME=kamponglocal
PG_PORT=5432
PG_PASSWORD=kampong

Clear, create database tables and import required data

On the command line in the project root directory:

yarn reset-db && yarn create-tables && yarn import-required

Populate database with mock data

On the command line in the project root directory:

yarn import-mock

NOTE: If mock data import fails, run the create database tables command and try again.

Database Migration

Migrations are used for version control of database schema in production. To make any changes to the database, create a new migration file.

On the command line in the project root directory:

#### List migrations that have completed and have yet to be run
yarn knex:migrate:list

#### Run all migration scripts that have not been run before
yarn knex:migrate:latest

#### Run all available seed files
yarn knex:seed:run

#### Create migration file
yarn knex:migrate:make

#### Create seed files
yarn knex:seed:make

#### Rollback the most recent migration
yarn knex:migrate:rollback

#### Rollback all migration
yarn knex:migrate:rollback all

Running the app

On the command line in the project root directory:

#### Build and run build in production
yarn build && yarn start

#### Run in development
yarn dev

Run tests

To run tests (written in Jest), on the command line in the project root directory:

#### Run entire test suite once
yarn test

#### Run test in watch mode
yarn test --watch

#### Update jest snapshot
yarn test --updateSnapshot

NOTE: To run the above commands on specific test file (or files in a directory), append the file or directory path to the respective command.

Run Prettier formatter

On the command line in the project root directory:

#### Format all files excluding those in .prettierignore file
yarn format

Cron jobs

Usage

• Database backup cron job runs at 5am daily to backup the application's database remotely.
• Featured listings shuffled at 12am daily.

Documentation

API Documentation

• Supported and running live on Kampong: https://kampong.app/api/docs

• Latest, unreleased version here

The Postman API Collection is available here, and can be imported into your Postman API client for API testing.

Database schema diagram can be found here.

License

• License: MIT