Sistema Tacet

Preview

• Absence Calendar

• Admin Dashboard

Prerequisites

• If you intend to contribute to this project ensure you have been added to the UW Blueprint Github Organization.
• Install Node.js (v22 tested). It's recommended to use NVM (Node Version Manager) to manage your Node.js versions.
• Install Docker Desktop (MacOS | Windows | Linux) and ensure that it is running.

Clone and Install

• 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
• Make sure you have been added to the Sistema HashiCorp Vault.
• 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

Running Only the Database

If you need to start only the database without running the frontend, use:

docker compose up db

This will start the db service without launching the nextjs service.

If you want the database to run in the background, use:

docker compose up -d db

To stop the database:

docker compose down

Accessing the Docker Container

To access the running Next.js container (sistema-nextjs-1), run:

docker exec -it sistema-nextjs-1 sh

This will open an interactive shell inside the container.

Accessing 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 Local Database

The local database seeds automatically when running:

docker compose up --build

However, if you need to manually seed the local database. First, ensure the local database is running:

docker compose up db

Then, run the following commands:

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

Seeding the Production Database

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

In your .env file, set the DATABASE_URL variable to the prod url from Vercel.

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.

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