Sistema

Setup

• Make sure you have been added to the UW Blueprint Github Workspace.

• Install Docker Desktop (MacOS | Windows | Linux) and ensure that it is running.

• Install Node.js (v22 tested). It's recommended to use NVM (Node Version Manager) to manage your Node.js versions.

  • Node.js for MacOS
  • Node.js for Windows
  • Node.js for Linux

• Clone the Sistema Github Repository to your local machine and cd into the project folder:

git clone https://github.com/uwblueprint/sistema.git
cd sistema

• Create a .env file in the root directory based on the .env.sample file. Update the environment variables as needed. Consult the Secrets section for detailed instructions.

cp .env.sample .env

• Install dependencies locally

npm install

• Build and start the Docker containers

docker-compose up --build

Secrets

• Create A HashiCorp Cloud Platform Account
• Install HashiCorp Vault in order to pull secrets
• In the folder where you cloned the Sistema repository, log into Vault

hcp auth login

• Configure the Vault Command Line Interface

hcp profile init

• Select the sistema Organization and Project

✔ Organization with name sistema ID 12cd56-88d2-69fb-8cc1-s3sAm3st selected
✔ Project with name sistema ID 12cd56-704c-46af-8ba5-mAtr3x selected
Use the arrow keys to navigate: ↓ ↑ → ←
? Select an application name:
  ▸ sistema

Copying secrets from the vault to local

• Copy secrets to a .env file

./setup_secrets.sh

Sending all local secrets to the vault (warning: this overwrites all secrets)

• Push secrets from .env file to HashiCorp Vault

./push_secrets.sh

Docker Commands

If you’re new to Docker, you can learn more about docker-compose commands at this docker compose overview.

# Start Docker Containers
docker-compose up --build

# Stop Containers
docker-compose down

# Remove Containers, Networks, and Volumes:
docker-compose down --volumes

# View Running Containers:
docker ps

# Clean Up Stopped Containers & Unused Resources:
docker system prune -a --volumes

Migrating After a Schema Change

# Generate Prisma Client:
npx prisma generate

# Apply Migrations:
npx prisma migrate dev

Accessing PostgreSQL Database

# Open a Postgres shell in the sistema-db -1 Docker container and connect to the sistema database
docker exec -it sistema-db-1 psql -U sistema -d sistema
# Retrieve all rows from the "Absence" table
SELECT * FROM public."Absence";
# Some other helpful commands:
# Display all table names
\dt
# Quit
\q
# Retrieve rows from other tables (don't forget the semicolon)
SELECT * FROM public."<table-name>";

Seeding the Production Database

The local database seeds automatically locally when docker compose build --up is run. Only run the commands below to seed the production database:

In the schema.prisma, set the db datasource as follows (where VERCEL_POSTGRES_PRISMA_URL and VERCEL_POSTGRES_URL_NON_POOLING are Vercel environment variables):

datasource db {
  provider = "postgresql"
  url = env("VERCEL_POSTGRES_PRISMA_URL")
  directUrl = env("VERCEL_POSTGRES_URL_NON_POOLING")
}

Then, run the following commands:

npx prisma generate
npx prisma db push
npx @snaplet/seed sync
npx prisma db seed

Formatting and Linting

Prettier

We use Prettier for code formatting. To check for formatting issues:

npm run prettier:check

To automatically fix formatting issues:

npm run prettier:fix

ESLint

We use ESLint for code linting. To check for linting issues:

npm run lint

To automatically fix linting issues:

npm run lint:fix

Combined Formatting and Linting

To run both Prettier and ESLint to format and fix linting issues in one command:

npm run format

Commits

• Commits should be atomic (guideline: the commit is self-contained; a reviewer could make sense of it even if they viewed the commit diff in isolation)

• Trivial commits (e.g. fixing a typo in the previous commit, formatting changes) should be squashed or fixup'd into the last non-trivial commit

# last commit contained a typo, fixed now
git add .
git commit -m "Fix typo"

# fixup into previous commit through interactive rebase
# x in HEAD~x refers to the last x commits you want to view
git rebase -i HEAD~2
# text editor opens, follow instructions in there to fixup

# force push to remote feature branch
git push -f

• Commit messages and PR names are descriptive and written in imperative tense. The first word should be capitalized. E.g. "Create user REST endpoints", not "Created user REST endpoints"
• PRs can contain multiple commits, they do not need to be squashed together before merging as long as each commit is atomic. Our repo is configured to only allow squash commits to main so the entire PR will appear as 1 commit on main, but the individual commits are preserved when viewing the PR.

Version Control Guide

• Branch off of main for all feature work and bug fixes, creating a "feature branch". Prefix the feature branch name with your name. The branch name should be in kebab case and it should be short and descriptive. E.g. chinemerem/readme-update

• To integrate changes on main into your feature branch, use rebase instead of merge

# currently working on feature branch, there are new commits on main
git pull origin main --rebase

# if there are conflicts, resolve them and then:
git add .
git rebase --continue

# force push to remote feature branch
git push -f