my-finance-pal-backend/README.md

My Finance Pal

Example Typescript Node.js webserivce showcasing best practices in software development
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation

About The Project

This is a standalone best practice web application developed for an engineering bootcamp for a lecture at the Technical University of Munich.

Please bear in mind that also this is not a perfect version of an application as one would imagine it running in production in a real world scenario. However, we tried to incorporate as many best practices as possible, but as few as needed to get students, who are on a beginner level, started. The goal is to have this is a toolbox for developing a state-of-the art Node.js Typescript business application.

Don't take everything we do in this application literally. It is important to also always think for yourself and consider which of the presented techniques and frameworks you actually need for your use case!

At the end, we hope that this helps you on your journey on becoming an amazing software developer and we hope you have fun exploring the universe of backend engineering :)

Disclaimer: A lot of the standard Node.js/Express code was to some parts inspired, to some copied over from PracticaJS. Please have a look at their work and examples as it gives you a great starting point and references when it comes to best practices with Node.js development. Also have a look at the Express Typescript Generator, which we also used to create the initial setup of our app.

(back to top)

Built With

• 
• 
• 
• 
• 

(back to top)

Getting Started

In order to be able to start the service locally, follow these required steps.

Prerequisites

Needed toolings and frameworks you should install before building the project:

• Node.js (if not already installed)

• Update npm

  npm install npm@latest -g
  

• Yarn

  npm install yarn -g
  

• GitHub CLI (optional but recommended)

  brew install gh
  

Installation

1. Clone the repo

   git clone https://github.com/ungaralex/my-finance-pal-backend.git
   

2. Install NPM packages

   yarn install
   

Run Locally

To run/debug the service locally in dev mode, only the following is needed:

1. Start the mongo service of the docker-compose file

    docker-compose up -d mongo
   

2. Start the my-finance-pal service.

   yarn dev
   

The service now runs on port 3000 and listens to requests

(back to top)

Google Cloud Platform (GCP) Infrastructure

We use Cloud Run. It is a serverless platform for deploying containerized applications. Besides Cloud Run, there are a few other supporting GCP services that we use, such as Cloud Build and Artifact Registry.

This section briefly describes how to setup the infrastructure resources using the gcloud CLI. For a production-ready setup, we strongly recommend not using the CLI, but rather adopting an Infrastructure-as-Code approach, e.g. using Terraform. For the scope of this demo application, the CLI is sufficient.

Infrastructure Setup Prerequisites

1. Open an account on GCP.
2. Create a new project on GCP.
3. Install the gcloud CLI.
4. Authenticate to GCP using: gcloud auth login.

Setup Steps

Start by setting the project ID:

gcloud config set project <GCP_PROJECT_ID>

Next, we'll enable a few services:

gcloud services enable cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com

• cloudbuild.googleapis.com -> Cloud Build, used to build the container images
• artifactregistry.googleapis.com -> Artifact Registry, used to store the container images
• run.googleapis.com -> Cloud Run, used to deploy the container images

Once that is done, we'll create an artifact repository to store the container images:

gcloud artifacts repositories create --location <GCP_REGION> cloud-run-builds --repository-format docker

Don't forget to replace the <GCP_REGION> placeholder with a region of your choice, e.g. europe-west1.

Now, we create a service account for GitHub Actions to use:

gcloud iam service-accounts create gh-actions

We'll use this service account in the next section to authenticate to GCP from GitHub Actions. Let's now grant a few permissions to the service account:

gcloud projects add-iam-policy-binding <GCP_PROJECT_ID> \
  --member=serviceAccount:gh-actions@<GCP_PROJECT_ID>.iam.gserviceaccount.com \
  --role=roles/cloudbuild.builds.editor

gcloud projects add-iam-policy-binding <GCP_PROJECT_ID> \
  --member=serviceAccount:gh-actions@<GCP_PROJECT_ID>.iam.gserviceaccount.com \
  --role=roles/cloudbuild.builds.viewer

gcloud projects add-iam-policy-binding <GCP_PROJECT_ID> \
  --member=serviceAccount:gh-actions@<GCP_PROJECT_ID>.iam.gserviceaccount.com \
  --role=roles/storage.admin

gcloud iam service-accounts add-iam-policy-binding \
  <GCP_PROJECT_NUMBER>-compute@developer.gserviceaccount.com \
  --member="serviceAccount:gh-actions@<GCP_PROJECT_ID>.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

As a rule of thumb, try to always keep the permissions as granular as possible and follow the least-privilege principle.

Note: <GCP_PROJECT_NUMBER>-compute@developer.gserviceaccount.com refers to the Compute Engine default service account. You can find the project number in the GCP console, or by running gcloud projects describe <GCP_PROJECT_ID> --format='value(projectNumber)'.

CI/CD Pipelines Using GitHub Actions

GitHub Actions is a reasonably good CI/CD platform. We use it to build and deploy this demo application to GCP. The .github/workflows directory contains the definitions for the CI and CD pipelines.

Authenticating to GCP using a Service Account Key

We use the auth action to authenticate to GCP using a service account key. The service account key is a long-lived credential, thus it's not ideal from a security perspective. For a production-ready setup, we strongly recommend using Workload Identity Federation instead.

Generate the service account key using the following command:

gcloud iam service-accounts keys create gh-actions-key.json --iam-account gh-actions@<GCP_PROJECT_ID>.iam.gserviceaccount.com

Populating Secrets in GitHub

The GCP service account key needs to be stored as a secret in the GitHub repo. Alongside, we store a few other GCP-related configuration values, such as project ID and region. Secrets can be accessed in the GitHub Actions workflows.

We advise using gh to create the secrets:

gh secret set GCP_PROJECT_ID --body '<GCP_PROJECT_ID>'
gh secret set GCP_REGION --body '<GCP_REGION>' # e.g. europe-west1
gh secret set GCP_SA_KEY --body $(cat <GPC_SERVICE_ACCOUNT_KEY.json> | base64)

The CI and CD workflows reference these secrets and will now be able to authenticate to GCP.