URL

API requests are routed through the domain petrolpal.online.

[!WARNING] Critical Warning! Some networks (including the UQ Wi-fi) may block this domain as it is a fresh HTTPS domain. Please disable firewall rules that may block this domain from being accessed.

Requirements

Before running startup, make sure you have:

• Valid Google Maps API key
• Terraform installed.
• Poetry installed.
• Docker running, because Terraform builds and pushes service images.
• Valid AWS credentials for the lab account/profile.
• Access to the configured AWS region, us-east-1.

If you are using the checked-in lab credentials file, export the profile before startup:

export AWS_SHARED_CREDENTIALS_FILE="$PWD/credentials"
export AWS_PROFILE="590183910851_CSSE6400-LabRole"
export AWS_DEFAULT_REGION="us-east-1"

Python dependencies for the startup helper are managed by the root Poetry project:

poetry install

Startup

From the repository root, run:

./scripts/startup.sh

The startup script:

1. Runs poetry install from the repository root to install helper-script dependencies such as boto3.
2. Runs terraform init in terraform/.
3. Runs terraform apply -auto-approve to deploy the AWS infrastructure and service containers.

Note: You will need to provide username and passcodes for databases, as well as a valid Google Maps API key to be utilised by the frontend* 4. Runs the station seed task through ECS:

poetry run python scripts/insert_stations/seed-stations.py

The station seeder does not connect to the stations database directly from your machine. It starts a one-off ECS task using the deployed price-service task, and that container seeds the private stations database from inside the AWS network.

More info in scripts/insert_stations/INSERT.md

Station Seed Data

Stations seeded into the map/database come from:

services/price-service/seed-data/qld_petrol_stations.json

To change which stations are inserted, edit that JSON file, then rerun startup or redeploy the price-service image and run:

poetry run python scripts/insert_stations/seed-stations.py

The JSON file is bundled into the price-service Docker image, so ECS will only see changes after the image has been rebuilt and redeployed.

How Notifications Work (Important before testing the system)

There are two separate confirmation emails in this system. They are completely independent of each other and both need to be completed for the full notification flow to work.

1. Cognito Sign-Up Confirmation

When a new user signs up through the frontend, AWS Cognito sends a verification email to confirm the account. The user must click the link in that email to activate their account and be able to log in. This is a one-time step for account creation only.

2. SNS Subscription Confirmation

When a logged-in user adds a postcode zone to their favourites for the first time, a second email is sent by AWS SNS asking the user to confirm their subscription to price alerts. This is an AWS requirement and cannot be skipped. SNS will not send notification emails to anyone who has not explicitly opted in.

• If the user clicks the confirmation link, their subscription becomes active and they will receive email alerts whenever a price drop is detected in any of their favourited zones.
• If the user does not confirm, they will not receive any price alert emails, even though their favourite zones are saved. The system will log these as not_subscribed in the notification logs. This is expected behaviour and not a bug.

Both confirmations are required by AWS and cannot be bypassed.

Running Test Files

Please refer to the README.md files under these directories:

/scripts /scripts/pipeline /scripts/scalability

For information on how to run our predefined test scripts