To get started, clone the repository and check out the Project Tracker.
You can contribute to the K-Scale Store project in various ways, such as reporting bugs, submitting pull requests, raising issues, or creating suggestions.
Important
You MUST access the locally run website through 127.0.0.1:3000
and NOT localhost:3000
. This is because the CORS policy is configured to only allow requests from the exact domain 127.0.0.1:3000
.
Note
You should develop the backend using Python 3.11 or later
Backend settings are located in the store/settings/
directory. You can specify which settings to use by setting the ENVIRONMENT
variable to the corresponding config file stem in store/settings/configs/
. For local development, this should typically be set to local
.
Place the required environment variables in env.sh
or .env.local
.
To run the server or tests locally, source the environment variables in each new terminal session:
source env.sh # or source .env.local
Example env.sh
/.env.local
file:
# Specifies a local environment versus production environment.
export ENVIRONMENT=local
# For AWS
export AWS_DEFAULT_REGION='us-east-1'
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_ENDPOINT_URL_S3='http://127.0.0.1:4566'
export AWS_ENDPOINT_URL_DYNAMODB='http://127.0.0.1:4566'
# For letting the frontend know the backend URL.
export VITE_APP_BACKEND_URL='http://127.0.0.1:8080'
# For SMTP
export SMTP_HOST='smtp.gmail.com'
export SMTP_SENDER_EMAIL=''
export SMTP_PASSWORD=''
export SMTP_SENDER_NAME=''
export SMTP_USERNAME=''
The repository's local configuration comes with Google OAuth credentials for a test application. Alternatively, you can set up your own Google OAuth application to test the application locally, by following the instructions here.
The repository's local configuration comes with Github OAuth credentials for a test application. Alternatively, you can set up your own Github OAuth application to test the application locally:
- Create an OAuth App on Github Developer Settings
- Set both Homepage URL and Authorization callback URL to
http://127.0.0.1:3000/login
before youUpdate application
on Github Oauth App configuration - Copy the Client ID and Client Secret from Github OAuth App configuration and set them in
GITHUB_CLIENT_ID
andGITHUB_CLIENT_SECRET
respectively
For local development, install the AWS CLI
and use the localstack/localstack
Docker image to run a local AWS instance:
docker pull localstack/localstack # If you haven't already
docker run -d --name localstack -p 4566:4566 -p 4571:4571 localstack/localstack
Then, if you need to kill the database, you can run:
docker kill localstack || true
docker rm localstack || true
Initialize the artifact bucket with:
aws s3api create-bucket --bucket artifacts
DynamoDB Admin provides a GUI for viewing your tables and their entries. To install, run:
npm i -g dynamodb-admin
To launch DynamoDB Admin, source the environment variables used for FastAPI, then run:
DYNAMO_ENDPOINT=http://127.0.0.1:4566 dynamodb-admin
Create a Python virtual environment using uv or virtualenv with Python 3.11 or later:
uv venv .venv --python 3.11 # Using uv
python -m venv .venv # Using vanilla virtualenv
source .venv/bin/activate
Install the project dependencies:
uv pip install -e '.[dev]' # Using uv
pip install -e '.[dev]' # Using vanilla pip
If additional packages are missing, try:
uv pip install -r store/requirements.txt -r store/requirements-dev.txt # Using uv
Initialize the test databases with:
python -m store.app.db create
Serve the FastAPI application in development mode:
make start-backend
After updating the backend API, regenerate the API client by running the following from the frontend
directory:
openapi-typescript http://localhost:8080/openapi.json --output src/gen/api.ts # While running the backend API locally
Install React dependencies using nvm and npm:
cd frontend
nvm use 20.10.0
npm install
Serve the React frontend in development mode:
npm run dev
Build the React frontend for production:
npm run build
Run code formatting:
npm run format
To run tests, use the following commands:
make test
make test-frontend # Run only the frontend tests
make test-backend # Run only the backend tests