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

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

• 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

• Build and start the Docker containers

docker-compose up --build

• Create A HashiCorp Clous Cloud Platform Account
• Install HashiCorp Vault in order to pull secrets
• Log in to Vault

vlt login

• Configure the Vault Command Line Interface

vlt config 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

• Copy secrets to a .env file

./setup_secrets.sh

• 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

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

# build Builds images
docker-compose

# builds images (if they don’t exist) & starts containers
docker-compose up 

# builds images & starts containers
docker-compose up --build

# stops the containers
docker-compose down 

# get Names & Statuses of Running Containers
docker ps

# run a bash shell in the container
docker exec -it sistema-db-1 /bin/bash

# in container now
psql -U sistema -d sistema

# in postgres shell, some common commands:
# display all table names
\dt
# quit
\q
# you can run any SQL query, don't forget the semicolon!
SELECT * FROM <table-name>;

• 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.