Makefile Command Reference¶

Complete reference for all Makefile commands in SYNDI.

Command Categories¶

Setup & Configuration
Development
Testing
Building
AWS Deployment
JWT Testing
Utilities

Setup & Configuration¶

setup-local¶

Set up local directories and configuration for development.

Usage:

make setup-local ENV=dev ORG=myorg

Parameters:

ENV - Environment (dev or test)
ORG - Organization identifier (required)

What it does:

Creates .local/s3/ directory structure
Creates simulated S3 buckets (forms, eln, eln-drafts, public, webapp, lambda)
Deploys configuration via make config

Example:

make setup-local ENV=dev ORG=uga

config¶

Deploy configuration files to runtime locations.

Usage:

make config ENV=dev ORG=myorg

Parameters:

ENV - Environment (dev, test, stage, prod)
ORG - Organization identifier (required)

What it does:

Cleans existing configs
Merges infra/.config/webapp/{env}.json + infra/.config/webapp/{env}-{org}.json
Writes to frontend/public/config.json
Merges infra/.config/lambda/{env}.json + infra/.config/lambda/{env}-{org}.json
Writes to backend/rawscribe/.config/config.json
Creates environment variables JSON for cloud deployments

Example:

make config ENV=stage ORG=uga

clean-config¶

Remove all generated configuration files.

Usage:

make clean-config

What it removes:

backend/rawscribe/.config/
frontend/public/config.json

list-orgs¶

List all configured organizations from samconfig.toml.

Usage:

make list-orgs

Note: If samconfig.toml doesn’t exist (current system), this shows no organizations.

list-envs¶

List all configured environments from samconfig.toml.

Usage:

make list-envs

Note: If samconfig.toml doesn’t exist (current system), this shows no environments.

schemas¶

Generate TypeScript schemas from SOP templates.

Usage:

make schemas

What it does:

Runs frontend/tools/generateSOPTemplateSchema.ts
Generates TypeScript interfaces from SOP YAML schema

docs¶

Build Sphinx documentation.

Usage:

make docs

What it does:

Builds HTML documentation in docs/build/html/

Development¶

start-backend¶

Start FastAPI backend server with hot reload.

Usage:

make start-backend ENV=dev ORG=myorg

Parameters:

ENV - Environment (dev, test, stage, prod)
ORG - Organization identifier (required)

What it does:

Deploys configuration for ENV/ORG
Creates symlink to .local/ storage
Starts uvicorn with auto-reload

Server:

URL: http://localhost:8000
API Docs: http://localhost:8000/docs
Hot reload: Enabled

Stop: Ctrl+C

start-frontend¶

Start React frontend dev server with hot reload.

Usage:

make start-frontend ENV=dev ORG=myorg

Parameters:

ENV - Environment (dev, test, stage, prod)
ORG - Organization identifier (required)

What it does:

Deploys configuration for ENV/ORG
Starts Vite dev server

Server:

URL: http://localhost:3000 or http://localhost:5173
Hot reload: Enabled (HMR)

Stop: Ctrl+C

start-dev¶

Start both backend and frontend servers.

Usage:

make start-dev ENV=dev ORG=myorg

Parameters:

ENV - Must be dev
ORG - Organization identifier (required)

What it does:

Starts backend in background
Starts frontend in foreground

Stop: Ctrl+C (stops frontend, use make stop-all to stop both)

stop-all¶

Stop all running development servers.

Usage:

make stop-all

What it does:

Runs scripts/stop-servers.sh
Kills uvicorn and vite processes

Testing¶

test-frontend¶

Run frontend unit tests (Vitest).

Usage:

make test-frontend
make test-frontend ORG=myorg  # Override org

Default ORG: testorg

What it does:

Deploys test configuration
Runs npx vitest run in frontend

test-backend¶

Run backend unit tests (pytest).

Usage:

make test-backend
make test-backend ORG=myorg  # Override org

Default ORG: testorg

What it does:

Sets up local test environment
Runs pytest tests/ in backend

test-unit¶

Run all unit tests (frontend + backend).

Usage:

make test-unit
make test-unit ORG=myorg  # Override org

Default ORG: testorg

test-e2e¶

Run end-to-end tests (Playwright).

Usage:

make test-e2e
make test-e2e ORG=myorg  # Override org

Default ORG: testorg

What it does:

Deploys test configuration
Runs npx playwright test in frontend

test-e2e-reviewsubmit¶

Run ReviewSubmitPanel component E2E tests.

Usage:

make test-e2e-reviewsubmit

test-e2e-integration¶

Run integration tests with real backend.

Usage:

make test-e2e-integration

What it does:

Starts backend server
Runs Playwright tests against real backend
Stops backend server

test-e2e-ui¶

Run E2E tests with visual UI runner.

Usage:

make test-e2e-ui

test-e2e-headed¶

Run E2E tests with visible browser.

Usage:

make test-e2e-headed

test-e2e-debug¶

Run E2E tests in debug mode.

Usage:

make test-e2e-debug

test-all¶

Run all tests (unit + E2E).

Usage:

make test-all
make test-all ORG=myorg  # Override org

Default ORG: testorg

test-ci¶

Run CI test suite with coverage.

Usage:

make test-ci

What it does:

Backend tests with coverage (pytest –cov)
Frontend tests with coverage (vitest –coverage)
Generates coverage reports

clean-test¶

Clean test artifacts.

Usage:

make clean-test

What it removes:

Coverage reports
Test results
Playwright reports
Python cache files

Building¶

build-frontend¶

Build frontend webapp (clean build).

Usage:

make build-frontend ENV=stage ORG=myorg

Parameters:

ENV - Environment (required)
ORG - Organization (required)

What it does:

Calls clean-frontend first
Deploys configuration
Runs npm run build
Creates frontend/dist/

Always clean build - Removes dist/ before building

build-backend¶

Build Lambda function (clean build).

Usage:

make build-backend ENV=stage ORG=myorg

Parameters:

ENV - Environment (required)
ORG - Organization (required)

What it does:

Calls clean-backend first
Builds Lambda package
Creates backend/.build/lambda/function.zip

Always clean build - Removes .build/ before building

clean-frontend¶

Remove frontend build artifacts.

Usage:

make clean-frontend

What it removes:

frontend/dist/
frontend/public/config.json
.local/s3/webapp/

clean-backend¶

Remove backend build artifacts.

Usage:

make clean-backend

What it removes:

backend/.build/
.local/s3/lambda/function.zip
.local/s3/lambda/build_mock/

serve-webapp¶

Serve built frontend locally.

Usage:

make serve-webapp ENV=stage ORG=myorg

Incremental build - Only rebuilds if sources changed

Server: Python static file server (emulates CloudFront+S3)

serve-lambda¶

Serve packaged Lambda locally.

Usage:

make serve-lambda ENV=stage ORG=myorg

Incremental build - Only rebuilds if sources changed

Server: Uvicorn serving packaged Lambda code

Note: Must use conda activate syndi (Python 3.9) for Lambda compatibility

serve-lambda-debug¶

Serve Lambda with forced rebuild and debug logging.

Usage:

make serve-lambda-debug ENV=stage ORG=myorg

Forces clean rebuild - Useful for debugging packaging issues

AWS Deployment (RAWSCRIBE)¶

rs-build¶

Build Lambda function and dependency layer with SAM.

Usage:

make rs-build ENV=stage ORG=myorg

Parameters:

ENV - Environment (required)
ORG - Organization (required)

What it does:

Deploys configuration
Copies requirements.txt to layer directory
Runs sam build --cached with org-specific build directory

Build directory: .aws-sam-{ENV}-{ORG}/

Time: 5-7 min (first build) or 30 sec (with cached layer)

rs-deploy¶

Full build and deploy to AWS.

Usage:

make rs-deploy ENV=stage ORG=myorg
ENABLE_AUTH=true CREATE_BUCKETS=true make rs-deploy ENV=stage ORG=myorg

Parameters:

ENV - Environment (required)
ORG - Organization (required)
ENABLE_AUTH - Enable Cognito (default: true)
CREATE_BUCKETS - Create S3 buckets (default: false)
ADMIN_USERNAME - Create admin user (optional)
ADMIN_PASSWORD - Admin password (optional)

What it does:

Calls rs-build
Calls rs-deploy-only

Time: 5-7 minutes

Use when: First deployment, dependency changes, infrastructure changes

rs-deploy-only¶

Deploy without building.

Usage:

make rs-deploy-only ENV=stage ORG=myorg

Parameters: Same as rs-deploy

What it does:

Handles ROLLBACK_COMPLETE state (auto-deletes failed stack)
Uploads config to S3
Deploys via SAM using existing build
Creates admin user if credentials provided

Time: 1-2 minutes

Use when: Config/parameter changes only

rs-deploy-function¶

Quick Lambda code update (bypasses CloudFormation).

Usage:

make rs-deploy-function ENV=stage ORG=myorg

Parameters:

ENV - Environment (required)
ORG - Organization (required)

What it does:

Creates minimal zip of code only (no dependencies)
Updates Lambda function directly via AWS API
Uses S3 if package > 69MB

Time: 30 seconds

Use when: Code changes only

rs-validate¶

Validate SAM template.

Usage:

make rs-validate

What it does:

Runs sam validate --lint

sync-configs¶

Sync configuration files from CloudFormation outputs.

Usage:

make sync-configs ENV=stage ORG=myorg

Parameters:

ENV - Environment (required)
ORG - Organization (required)

What it does:

Queries CloudFormation stack outputs
Updates infra/.config/webapp/{env}-{org}.json
Updates infra/.config/lambda/{env}-{org}.json
Preserves custom fields

rs-sync¶

Sync Lambda code only (SAM sync).

Usage:

make rs-sync ENV=stage ORG=myorg

What it does:

Uses sam sync --code to update Lambda
Faster than full deployment

Time: 10-20 seconds

rs-sync-watch¶

Sync Lambda code in watch mode.

Usage:

make rs-sync-watch ENV=stage ORG=myorg

What it does:

Watches for file changes
Automatically syncs to Lambda
Press Ctrl+C to stop

rs-watch-log¶

View Lambda logs in real-time.

Usage:

make rs-watch-log ENV=stage ORG=myorg

Parameters:

ENV - Environment (required)
ORG - Organization (required)

What it does:

Tails CloudWatch logs for Lambda function
Shows logs in real-time

Stop: Ctrl+C

rs-teardown¶

Remove CloudFormation stack.

Usage:

make rs-teardown ENV=stage ORG=myorg

WARNING: Deletes Lambda, API Gateway, and CloudFormation stack. S3 buckets and Cognito User Pool may be preserved depending on template configuration.

Confirmation: 5 second wait before execution

JWT Testing¶

test-jwt-local¶

Test JWT authentication locally (no AWS).

Usage:

make test-jwt-local ENV=stage ORG=myorg

Environment variables required:

export MYORG_TEST_USER=testuser@myorg.com
export MYORG_TEST_PASSWORD=TestPass123!

(ORG name uppercased)

test-jwt-aws¶

Test JWT authentication on deployed Lambda.

Usage:

make test-jwt-aws ENV=stage ORG=myorg

Environment variables required: Same as test-jwt-local

What it does:

Discovers API Gateway and Cognito resources
Obtains JWT token
Tests protected endpoint

test-jwt-regression¶

Run full JWT regression test suite.

Usage:

make test-jwt-regression

What it does:

Runs backend/test_jwt_regression.py
Tests all JWT validation scenarios

test-jwt-regression-local¶

Run JWT regression tests (local only, no AWS).

Usage:

make test-jwt-regression-local

get-rs-token¶

Get JWT token for testing.

Usage:

TOKEN=$(make get-rs-token ENV=stage ORG=myorg \
  USER_NAME=admin@myorg.com PASSWORD=YourPassword)

Parameters:

ENV - Environment (required)
ORG - Organization (required)
USER_NAME - Username/email (required) Note: Use USER_NAME not USERNAME
PASSWORD - User password (required)

Output: JWT access token (to stdout)

Utilities¶

show-account-number¶

Display current AWS account number.

Usage:

make show-account-number

show-region¶

Display current AWS region.

Usage:

make show-region

show-rs-endpoint¶

Show API Gateway endpoint URL.

Usage:

make show-rs-endpoint ENV=stage ORG=myorg

show-rs-function-name¶

Show Lambda function name.

Usage:

make show-rs-function-name ENV=stage ORG=myorg

show-rs-user-pool¶

Show Cognito User Pool ID.

Usage:

make show-rs-user-pool ENV=stage ORG=myorg

show-rs-client-id¶

Show Cognito App Client ID.

Usage:

make show-rs-client-id ENV=stage ORG=myorg

show-rs-api-gateway¶

Show API Gateway name.

Usage:

make show-rs-api-gateway ENV=stage ORG=myorg

show-rs-s3-buckets¶

Show S3 buckets for organization.

Usage:

make show-rs-s3-buckets ENV=stage ORG=myorg

Displays:

Shared deployment bucket
Org-specific buckets (filtered by ENV/ORG)

show-rs-stackname¶

Show CloudFormation stack name.

Usage:

make show-rs-stackname ENV=stage ORG=myorg

check-rs-stack-status¶

Check CloudFormation stack status.

Usage:

make check-rs-stack-status ENV=stage ORG=myorg

Possible statuses:

CREATE_COMPLETE - Stack created successfully
UPDATE_COMPLETE - Stack updated successfully
ROLLBACK_COMPLETE - Deployment failed (needs deletion)
NO_STACK - Stack doesn’t exist

check-rs¶

Check complete deployment status.

Usage:

make check-rs ENV=stage ORG=myorg
make check-rs  # Checks all orgs

Displays:

Lambda function name
API Gateway name
API endpoint URL
Stack name
User Pool ID
Client ID
All S3 buckets

Common Command Patterns¶

Development Workflow¶

# Start development
make setup-local ENV=dev ORG=myorg
make start-dev ENV=dev ORG=myorg

# Test changes
make test-all

# Deploy to staging
make rs-deploy-function ENV=stage ORG=myorg

Testing Workflow¶

# Run all tests
make test-all

# Run specific tests
make test-frontend
make test-backend
make test-e2e

# Test authentication
make test-jwt-aws ENV=stage ORG=myorg

Deployment Workflow¶

# First deployment
ENABLE_AUTH=true CREATE_BUCKETS=true \
  ADMIN_USERNAME=admin@myorg.com ADMIN_PASSWORD=Pass! \
  ORG=myorg ENV=stage make rs-deploy

# Sync configs
make sync-configs ENV=stage ORG=myorg

# Subsequent code updates
make rs-deploy-function ENV=stage ORG=myorg

# Config updates
make rs-deploy-only ENV=stage ORG=myorg

Monitoring Workflow¶

# Check status
make check-rs ENV=stage ORG=myorg

# View logs
make rs-watch-log ENV=stage ORG=myorg

# Check stack
make check-rs-stack-status ENV=stage ORG=myorg

Parameter Reference¶

Required Parameters¶

ENV - Environment name (dev, test, stage, prod)
ORG - Organization identifier (lowercase alphanumeric, no default for security)

Optional Parameters¶

ENABLE_AUTH - Enable Cognito (true/false, default: true)
CREATE_BUCKETS - Create S3 buckets (true/false, default: false)
ADMIN_USERNAME - Admin user email (default: none)
ADMIN_PASSWORD - Admin password (default: none)
USER_NAME - Username for get-rs-token (default: none)
PASSWORD - Password for get-rs-token (default: none)

Test Default¶

TEST_ORG - Default organization for tests (default: testorg)

Help Commands¶

help¶

Show all available commands.

Usage:

make help
make  # Same as make help

help-target¶

Show detailed help for specific target.

Usage:

make help-target TARGET=rs-deploy

Example:

make help-target TARGET=rs-deploy-function

Makefile Command Reference¶

Command Categories¶

Setup & Configuration¶

setup-local¶

config¶

clean-config¶

list-orgs¶

list-envs¶

schemas¶

docs¶

Development¶

start-backend¶

start-frontend¶

start-dev¶

stop-all¶

Testing¶

test-frontend¶

test-backend¶

test-unit¶

test-e2e¶

test-e2e-reviewsubmit¶

test-e2e-integration¶

test-e2e-ui¶

test-e2e-headed¶

test-e2e-debug¶

test-all¶

test-ci¶

clean-test¶

Building¶

build-frontend¶

build-backend¶

clean-frontend¶

clean-backend¶

serve-webapp¶

serve-lambda¶

serve-lambda-debug¶

AWS Deployment (RAWSCRIBE)¶

rs-build¶

rs-deploy¶

rs-deploy-only¶

rs-deploy-function¶

rs-validate¶

sync-configs¶

rs-sync¶

rs-sync-watch¶

rs-watch-log¶

rs-teardown¶

JWT Testing¶

test-jwt-local¶

test-jwt-aws¶

test-jwt-regression¶

test-jwt-regression-local¶

get-rs-token¶

Utilities¶

show-account-number¶

show-region¶

show-rs-endpoint¶

show-rs-function-name¶

show-rs-user-pool¶

show-rs-client-id¶

show-rs-api-gateway¶

show-rs-s3-buckets¶

show-rs-stackname¶

check-rs-stack-status¶

check-rs¶

Common Command Patterns¶

Development Workflow¶

Testing Workflow¶

Deployment Workflow¶

Monitoring Workflow¶

Parameter Reference¶

Required Parameters¶

Optional Parameters¶

Test Default¶

Help Commands¶

help¶

help-target¶

Related Documentation¶