Installation

This page covers a local or VM checkout. AWS deployment details live in the SAM targets in the root Makefile and related deployment docs.

Repository Checkout

git clone https://github.com/Plant-Tracer/webapp.git webapp
cd webapp

Install Dependencies

Use the Makefile target for your platform:

make install-ubuntu
make install-macos

The Makefile installs Python dependencies with Poetry into .venv and runs npm ci for JavaScript dependencies.

Local Application

make start-local-services
make make-local-demo
make run-local-debug

Flask runs on http://localhost:8080. lambda-resize runs locally on http://127.0.0.1:9811 when started by make run-local-lambda-debug or by make run-local-debug on macOS.

Non-Demo Course

Create a course with dbutil:

AWS_REGION=local poetry run python src/dbutil.py create-course \
  --course_name "My Course Name" \
  --course_id "Plant101" \
  --admin_email your_admin_email@example.com \
  --admin_name "Your Name"

dbutil prints the generated course key. Give that key to students so they can register.

Mailer Configuration

Local development uses Mailpit through SMTPCONFIG_JSON set by the Makefile. The Lambda-only stack uses AWS SES with the configured SERVER_EMAIL sender identity and SERVER_EMAIL_NAME display name. See Identity Management for the distinction between the server sender and course administrators. Verify the exact SERVER_EMAIL address in SES in the deployment region before using registration or resend-login on a deployed stack.

If you are deploying a non-production stack and cannot send SES mail as the configured SERVER_EMAIL, set the SAM MailerDryRun parameter to true. The stack will deploy and registration/resend-login will render email into Lambda logs instead of sending it. Use only test users in this mode because the logs include login links and API keys. Production stacks must use MailerDryRun=false with the SES sender verified.

For a non-Lambda SMTP mailer, provide one of:

  • PLANTTRACER_CREDENTIALS pointing at an INI file with [smtp].

  • SMTPCONFIG_JSON with SMTP settings.

  • SMTPCONFIG_ARN pointing at an AWS Secrets Manager secret.

Example INI section:

[smtp]
SMTP_USERNAME=plantadmin@example.com
SMTP_PASSWORD=secret
SMTP_PORT=587
SMTP_HOST=smtp.example.com

Validation

make lint
make pytest
make jscoverage
make check