Financer

Financer is a simple financial tracker app that helps you track monthly expenses, income, savings, and investments.

Table of Contents

• 🚀 Quick Start
• Requirements
• Create an OAuth App for Development
• Local Development Setup
  • 1. Clone the Repository
  • 2. Add OAuth Tokens
• Start the Development Environment
  • 1. Use the correct Node version
  • 2. Start the App
• Installing New Dependencies
  • Frontend
  • Backend
• Updating Types
• Testing Guide
  • Unit Tests
  • End-to-End Tests
  • Type Checking
• Production Tooling
  • Update the Database version
    • 1. Create a new backup from the database
    • 2. Check that the backup was successful
    • 3. If the job status is Completed, delete the manual job
    • 4. Delete the existing PostgreSQL cluster
    • 5. Deploy a new PostgreSQL instance with the latest version, update image tag before applying
    • 6. Wait for the new PostgreSQL instance to be ready
    • 7. List all backups in the /backup folder
    • 8. Restore the backup to the new PostgreSQL instance
    • 9. Restart the web application deployment to refresh the DB connection
• Adding TEST_ROLE to Users (Development Only)
• Authors

🚀 Quick Start

Follow this guide to quickly set up your local development environment.

Requirements

• Docker
• Docker Compose
• NVM
• GitHub account (for OAuth setup)

Create an OAuth App for Development

1. Visit the GitHub Developer Settings and click New OAuth App.
2. Fill out the form with the following details:
   • Application Name: Can be anything you like.
   • Homepage URL: http://localhost:3000/
   • Authorization Callback URL: http://localhost:3000/auth/github/redirect
3. Register the application.

Local Development Setup

1. Clone the Repository

git clone git@github.com:sebarickert/financer.git
cd financer

2. Add OAuth Tokens

cd backend
cp .env .env.local

Edit the .env.local file and add your GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET.

Start the Development Environment

1. Use the correct Node version

nvm use    # Install Node version (via nvm)
npm ci     # Install dependencies

2. Start the App

npm start

Installing New Dependencies

Frontend

npm -w frontend install DEPENDENCY-NAME

Backend

npm -w backend install DEPENDENCY-NAME

Updating Types

To update the types, run:

npm run types:update

This will export the types from the backend, copy the API spec to the frontend, and generate the necessary types for both the frontend and Playwright.

By following these commands, you can ensure that your codebase remains robust and maintainable.

Testing Guide

To ensure the quality and reliability of the application, we have set up various testing commands. Below are the commands you can use to run different types of tests:

Unit Tests

To run unit tests for both the backend and frontend, use the following command:

npm run test

End-to-End Tests

We use Playwright for end-to-end testing. You can run the tests using the following commands:

• To run all end-to-end tests:

npm run e2e:test

• To run end-to-end tests against an external server:

npm run e2e:test:external

• To open the Playwright test UI:

npm run e2e:open

• To open the Playwright test UI against an external server:

npm run e2e:open:external

Type Checking

To check the types across the workspace, use:

npm run check-types

Production Tooling

Update the Database version

1. Create a new backup from the database

kubectl create job --from=cronjob/postgres-backup postgres-backup-manual -n financer

2. Check that the backup was successful

kubectl get pods -n financer

You should find jobs postgres-backup-manual-xxxxx with status Completed. Example output:

NAME                          READY   STATUS      RESTARTS   AGE
postgres-backup-manual-x2nt9  0/1     Completed   0          61s

3. If the job status is Completed, delete the manual job

kubectl delete job postgres-backup-manual -n financer

4. Delete the existing PostgreSQL cluster

kubectl delete -f kubernetes/production.postgres-deployment.yaml

5. Deploy a new PostgreSQL instance with the latest version, update image tag before applying

kubectl apply -f kubernetes/production.postgres-deployment.yaml

6. Wait for the new PostgreSQL instance to be ready

kubectl rollout status statefulset/postgres-deployment -n financer

7. List all backups in the /backup folder

kubectl run -i --tty --rm list-backups --image=busybox --restart=Never --namespace=financer --overrides='
{
  "apiVersion": "v1",
  "spec": {
    "containers": [
      {
        "name": "list-backups",
        "image": "busybox",
        "stdin": true,
        "tty": true,
        "command": ["/bin/sh", "-c", "ls -lh /backup"],
        "volumeMounts": [
          {
            "name": "backup-volume",
            "mountPath": "/backup"
          }
        ]
      }
    ],
    "volumes": [
      {
        "name": "backup-volume",
        "persistentVolumeClaim": {
          "claimName": "postgres-backup-volume"
        }
      }
    ]
  }
}'

8. Restore the backup to the new PostgreSQL instance

Note: Please find the backup name from the list-backups output and use the backup that you created in step 1.

BACKUP_NAME=financer_20XX-XX-XX_XX-XX.backup
kubectl run -i --tty --rm postgres-restore --image=postgres:latest --restart=Never --namespace=financer --overrides="
{
  \"apiVersion\": \"v1\",
  \"spec\": {
    \"containers\": [
      {
        \"name\": \"postgres-restore\",
        \"image\": \"postgres:latest\",
        \"stdin\": true,
        \"tty\": true,
        \"command\": [\"/bin/sh\", \"-c\", \"PGPASSWORD=\$POSTGRES_PASSWORD pg_restore -U \$POSTGRES_USER -h \$POSTGRES_HOST -p \$POSTGRES_PORT -d \$POSTGRES_DB /backup/$BACKUP_NAME\"],
        \"env\": [
          {
            \"name\": \"POSTGRES_DB\",
            \"value\": \"financer\"
          },
          {
            \"name\": \"POSTGRES_USER\",
            \"value\": \"admin\"
          },
          {
            \"name\": \"POSTGRES_HOST\",
            \"value\": \"postgres\"
          },
          {
            \"name\": \"POSTGRES_PORT\",
            \"value\": \"5432\"
          },
          {
            \"name\": \"POSTGRES_PASSWORD\",
            \"valueFrom\": {
              \"secretKeyRef\": {
                \"name\": \"database-credentials\",
                \"key\": \"DB_PASSWORD\"
              }
            }
          }
        ],
        \"volumeMounts\": [
          {
            \"name\": \"backup-volume\",
            \"mountPath\": \"/backup\"
          }
        ]
      }
    ],
    \"volumes\": [
      {
        \"name\": \"backup-volume\",
        \"persistentVolumeClaim\": {
          \"claimName\": \"postgres-backup-volume\"
        }
      }
    ]
  }
}"

9. Restart the web application deployment to refresh the DB connection

kubectl rollout restart deployment webapp-deployment -n financer

Adding TEST_ROLE to Users (Development Only)

For development purposes, you can assign the TEST_ROLE to all users by running the following command:

npm run setup:development-users

Authors

• Sebastian Rickert - sebarickert
• Teemu Sillantaus - silte