Developer Setup

Requirements

• Python 3.12

• Poetry

• Node.js 20.8.1 or newer and npm

• Java runtime for DynamoDB Local

• Git and GitHub CLI (gh)

• Chrome or Chromium for browser tests

• Make

Use the platform-specific setup pages for OS package details:

• Developer Setup Mac

• Setting Up Plant Tracer On Ubuntu 24.04

• Windows Developer Setup Notes

Clone And Install

git clone https://github.com/Plant-Tracer/webapp.git webapp
cd webapp
make install-macos      # macOS
make install-ubuntu     # Ubuntu

The Makefile creates an in-project Poetry environment at .venv.

Local Services

Start all local services:

make start-local-services

This starts:

• DynamoDB Local on http://localhost:8000/

• MinIO on http://localhost:9000/

• Mailpit on http://localhost:8025/ for the web UI and port 1025 for SMTP

Seed local data:

make make-local-demo

Storage Modes

The local checkout can run against either local storage emulators or remote AWS storage. Pick one mode per shell.

Local storage mode is the default. Leave AWS_REGION unset, or set it to local. The Makefile sets DynamoDB Local and MinIO endpoint overrides, PLANTTRACER_S3_BUCKET=planttracer-local, and DYNAMODB_TABLE_PREFIX=demo-:

make show-storage-mode
eval "$(make show-local-vars)"
make start-local-services
make make-local-demo
make run-local-lambda-debug
make run-local-debug

show-local-vars prints shell commands for the complete non-demo local debug environment. Evaluating its output configures subsequent direct commands, such as poetry run dbutil report, to use DynamoDB Local and MinIO. It also clears AWS profiles and demo-mode variables so they cannot override the local setup.

Remote storage mode runs local Flask and, if needed, the local lambda debug bridge against real AWS S3 and DynamoDB. Use this only with a development bucket and table prefix unless you explicitly intend to modify shared data. The Makefile requires the remote storage settings to be explicit and unsets local endpoint overrides for the remote debug targets:

AWS_PROFILE=plantadmin \
AWS_REGION=us-east-1 \
PLANTTRACER_S3_BUCKET=planttracer-dev \
DYNAMODB_TABLE_PREFIX=dev- \
make show-storage-mode

AWS_PROFILE=plantadmin \
AWS_REGION=us-east-1 \
PLANTTRACER_S3_BUCKET=planttracer-dev \
DYNAMODB_TABLE_PREFIX=dev- \
make run-remote-lambda-debug

AWS_PROFILE=plantadmin \
AWS_REGION=us-east-1 \
PLANTTRACER_S3_BUCKET=planttracer-dev \
DYNAMODB_TABLE_PREFIX=dev- \
make run-remote-debug

Do not run make make-local-demo for remote storage mode. That target is intentionally tied to DynamoDB Local and MinIO.

Run Locally

Normal local development uses two processes:

make run-local-lambda-debug
make run-local-debug

run-local-debug starts Flask on http://localhost:8080 in non-demo mode and prints a local admin login link. On macOS it also attempts to open the local Lambda debug process automatically.

Demo mode:

make run-local-demo-debug

Validation

Use the Makefile entry points:

make lint
make pytest
make jscoverage
make check

Do not bypass the Makefile for normal testing. The Makefile sets the local AWS, DynamoDB, MinIO, Mailpit, and Python path environment needed by tests.

Create A Course

AWS_REGION=local poetry run dbutil create-course \
  --course_name "Test Course" \
  --course_id "test" \
  --admin_email admin@example.com \
  --admin_name "Admin User"

For most local development, prefer make make-local-demo and the login link printed by make run-local-debug.

Cleanup

make stop-local-services
make delete-local
make wipe-local

delete-local stops services and removes local artifacts. wipe-local removes local artifacts, restarts services, and recreates the local bucket.