Compass is a tool to help educators create and manage Individualized Education Programs (IEPs) for better student outcome.
Useful resources:
Install Docker Desktop
Clone the GitHub repo:
git config --global core.autocrlf false
cd <parent folder of compass>
git clone https://github.com/sfbrigade/compass.git
cd compass
Create the local server env file:
cp .env.example .env.local
There are two ways to run Compass locally:
Option 1: Run server locally, and supporting services in Docker
Install node dependencies, starting in the compass
directory
npm install # install dependencies
Start services in Docker & reset the database
docker compose -f supporting_services/docker-compose.yml up -d # start the services in the background
npm run db:reset # reset and migrate the database
Start the server
npm run dev # start the server in development mode
Server URL: http://localhost:3000
NOTE: If you get into a login loop, double check that the Docker services are running
Seed database (Optional)
npm run db:seed # Seed the database with test data
# Must be done after login to Compass app
Option 2: Run both server and supporting services locally
Install dependencies, starting in the compass
directory
npm install # install dependencies
Reset the database and bring up the server
npm run db:reset # reset and migrate the database
npm run dev # start the server in development mode
Server URL: http://localhost:3000
.env.local file will need to be updated for sign in with Google
To update GOOGLE_CLIENT_ID:
Navigate to Google Cloud
Create a "Client ID for Web application"
Populate the fields as below (note the name and authorized redirect URIs fields)
Copy the client ID field on the upper right of the modal (not shown in screenshot), after creation
To update GOOGLE_CLIENT_SECRET:
The database container does not need to be started to run tests, but Docker Desktop must be running in the background.
Run all tests with npm run test
. An individual test file can be run with npm run test <path/to/file>
(e.x. npm run test src/routes/students.test.ts
).
To run tests in watch mode, use npm run test:watch
. This will run tests whenever a file is changed, but will not take database schema changes into account.
Until Compass is deployed, the initial migration file at src/api/db/migrations/1_initial-migrations.sql
should be edited. Once Compass is deployed, new migrations can be created in the same directory by adding 1
to the number of the last migration file.
Run npm run db:migrate
to migrate the database. However, until Compass is deployed, you'll more likely want to run npm run db:reset
to reset the database since we'll be making changes to the initial migration file.
Compass app is not running:
Make sure that Docker is running in the background
Client id is required:
Fill out the Google Client ID and Google Client Secret in .env.local