sasa-membership/QUICKSTART.md

Quick Start Guide

Starting the System

# Start all services
docker compose up -d

# Watch the logs until services are ready
docker compose logs -f

Wait until you see "Application startup complete", then press Ctrl+C.

Access the API:

• API: http://localhost:8050/api/v1
• Docs: http://localhost:8050/docs

API datetimes are stored and returned in UTC/Zulu. The frontend shows member-facing times in Europe/London and converts event input back to UTC before saving.

Set APP_PORT in .env / .env.example to change 8050. For Square payment form testing, use HTTPS at https://localhost:8443. Set APP_TLS_PORT in .env / .env.example to change 8443. TLS certs are auto-generated by the gateway container on first start.

Restart With Tests

Use the restart helper when you want to rebuild, run the fast test suite, and restart only after tests pass:

./restart.sh

It runs:

• docker compose run --rm frontend npm test
• docker compose run --rm backend pytest -q

The current tests cover frontend profile-question visibility/editability rules and backend profile-question answer normalization/validation. They are designed to complete quickly.

Testing the API

1. Register a new user

curl -X POST "http://localhost:8050/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "testpass123",
    "first_name": "Test",
    "last_name": "User"
  }'

2. Login

curl -X POST "http://localhost:8050/api/v1/auth/login-json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "testpass123"
  }'

Save the access_token from the response.

3. Get your profile

curl -X GET "http://localhost:8050/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

4. List membership tiers

curl -X GET "http://localhost:8050/api/v1/tiers/"

Docker Compose Commands

# Start services
docker compose up -d

# Stop services
docker compose down

# View logs (all services)
docker compose logs -f

# View logs (specific service)
docker compose logs -f backend

# Restart services
docker compose restart

# Rebuild after code changes
docker compose up -d --build

# Check status
docker compose ps

# Tail gateway logs
docker compose logs -f gateway

Default Admin Access

• Email: admin@swanseaairport.org
• Password: admin123

⚠️ Change this password immediately!

Common Tasks

Create a membership tier (admin)

1. Login as admin
2. Use the token in the Authorization header
3. POST to /api/v1/tiers/

Record a manual payment (admin)

1. Login as admin
2. POST to /api/v1/payments/manual-payment

View all users (admin)

1. Login as admin
2. GET /api/v1/users/

Manage profile questions (admin)

1. Login as admin or super admin
2. Open the dashboard Admin area
3. Create, edit, deactivate, and order configurable profile questions
4. Use dependencies to show questions only after a matching parent answer

Edit member profile answers

1. Members can update normal profile questions from the Questions dashboard tab
2. Admin-only answers, such as verified training fields, must be updated by an admin

Manage events and RSVPs

1. Admins can create and edit events from the dashboard
2. Members can view upcoming events and submit RSVP status
3. Admins can view RSVP lists and attendance data

ESP RFID readers

1. Readers register with /api/v1/esp/device/register
2. Readers sync clocks from /api/v1/esp/device/time
3. Tap, heartbeat, and write-job timestamps are UTC-normalized in the backend
4. Admins can review readers, taps, attendance, and card-write jobs from the ESP screens

Manage email templates and bounces

1. Super admins can edit database-backed email templates; previews are shown as escaped HTML text
2. SMTP2GO bounce webhooks are stored and visible in bounce management
3. Bounce cleanup and manual deactivation are available through the API/admin screens

Troubleshooting

Check service status

docker compose ps

View all logs

docker compose logs -f

View backend logs only

docker compose logs -f backend

Restart everything

docker compose restart

Clean start (removes all data)

docker compose down -v
docker compose up -d

Next Steps

1. Update .env with your Square and SMTP2GO credentials
2. Change the default admin password
3. Create additional admin users
4. Configure membership tiers as needed
5. Test payment processing
6. Customize email templates
7. Configure profile questions for onboarding and volunteer data
8. Use ./restart.sh before deploying changes so frontend and backend unit tests run first