Originally created by Julia Ying, Grace Kim, Ritika Bhatnagar, Aasha Jain
Ask your team lead for shared API keys and any email credentials you do not generate yourself.
1. Download PostgreSQL
You need Postgres for DATABASE_URL. Install, start it, then create the database:
brew install postgresql@16
brew services start postgresql@16
export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
createdb tigerliftAdd the export PATH=... line to ~/.zshrc so createdb / psql work in new terminals. If createdb says the database already exists, you are set.
Then ask your copilot (Cursor, Copilot, or any AI coding assistant) for your Postgres database URL so you can put it in .env. It should look like:
DATABASE_URL=postgresql://YOUR_MAC_USERNAME@localhost:5432/tigerliftUse your Mac username (whoami) in place of YOUR_MAC_USERNAME.
2. Generate a secret app key
python3 -c "import secrets; print(secrets.token_hex(32))"3. Create .env in the project root (TigerLift/.env)
APP_SECRET_KEY=
DATABASE_URL=postgresql://YOUR_MAC_USERNAME@localhost:5432/tigerlift
EMAIL_ADDRESS=
EMAIL_PASSWORD=
EMAILS_ON=False
FLASK_ENV=developmentPaste the secret from step 2 into APP_SECRET_KEY and the Postgres URL from step 1 into DATABASE_URL. Leave email blank and EMAILS_ON=False unless your team lead gives you credentials.
4. Frontend .env (optional for now)
Skip this for now. The servers can start without a Google API key; address autocomplete will not work until you add frontend/.env with VITE_GOOGLE_API_KEY= from your team lead.
5. Start the servers
Once Postgres and the root .env are ready, ask your copilot to start the localhost servers, or run them yourself:
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.pycd frontend
npm install
npm run devIf psycopg2 fails to install, run source ~/.zshrc and try pip install again. The app is at http://localhost:5173/. The backend uses http://localhost:5001/ because macOS AirPlay often takes port 5000. Princeton CAS login is still required to use the app.
The tests use a separate database, so they never touch your real data:
createdb tigerlift_test
cd backend
source .venv/bin/activate
pip install -r requirements-dev.txt
python -m pytest testsTo use a different test database, set TEST_DATABASE_URL.
Production runs on AWS EC2, not Heroku. Merging to main runs the Check and
deploy TigerLift GitHub Actions workflow: backend tests against an isolated
PostgreSQL database, a fresh frontend build, then deployment over AWS SSM.
There is no separate frontend build PR and no need to commit frontend/dist.
The workflow uses GitHub OIDC and the narrowly scoped TigerLiftGitHubDeployRole.
Its only build secret is VITE_GOOGLE_API_KEY; production database and mail
credentials stay on the server. Pull requests run checks without deployment access.
See deployment operations for health checks, rollback and host setup.