Skip to content

Latest commit

 

History

History
277 lines (192 loc) · 7.69 KB

CONTRIBUTING.md

File metadata and controls

277 lines (192 loc) · 7.69 KB
Raw

Getting Started

To get started, clone the repository and check out the Project Tracker.

You can contribute to the K-Scale WWW 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

Development

  1. Development Setup
  2. Database Setup
  3. FastAPI Setup
  4. Syncing Frontend and Backend
  5. React Setup
  6. Testing

Development Setup

Configuration

Backend settings are located in the www/settings/ directory. You can specify which settings to use by setting the ENVIRONMENT variable to the corresponding config file stem in www/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=''

# For Github OAuth
export GITHUB_CLIENT_ID=''
export GITHUB_CLIENT_SECRET=''

# For Google OAuth
export VITE_GOOGLE_CLIENT_ID=''

# For OnShape
export ONSHAPE_ACCESS_KEY=''
export ONSHAPE_SECRET_KEY=''

Google OAuth Configuration

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.

Github OAuth Configuration

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:

  1. Create an OAuth App on Github Developer Settings
  2. Set both Homepage URL and Authorization callback URL to http://127.0.0.1:3000/login before you Update application on Github Oauth App configuration
  3. Copy the Client ID and Client Secret from Github OAuth App configuration and set them in GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET respectively

Database Setup

DynamoDB/S3

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

Admin Panel

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

FastAPI Setup

Creating a Python Virtual Environment

Create a Python virtual environment using uv or virtualenv with Python 3.11 or later:

  1. Using uv:
uv venv .venv --python 3.11
  1. Using virtualenv: If you choose to use virtualenv, ensure that Python 3.11 is installed on your machine. You can check if it's installed by running:
python3.11 --version

If Python 3.11 is installed, create the virtual environment with:

python3.11 -m venv .venv

Note: If Python 3.11 is not installed on your machine, you will need to install it before proceeding. For macOS, you can install Python 3.11 using Homebrew:

brew install [email protected]

Activate the virtual environment:

Once the virtual environment is created, activate it:

source .venv/bin/activate

Installing Project Dependencies

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 www/requirements.txt -r www/requirements-dev.txt  # Using uv

Initializing the Test Databases

Initialize the test databases with:

python -m www.app.db create

Running the FastAPI Application

Serve the FastAPI application in development mode:

make start

Syncing Frontend and 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

React Setup

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

Testing

To run tests, use the following commands:

  1. Run autoformatting: make format
  2. Run static checks: make static-checks
  3. Run unit tests: make test
make test

Optional

Install pre-commit from here to run the formatting and static checks automatically when you commit.

Here's the pre-commit yaml configuration:

fail_fast: true
repos:
  - repo: local
    hooks:
      - id: format
        name: Format
        entry: bash -c 'make format || (echo "❌ Formatting failed. Please run make format manually and commit the changes." && exit 1) && git diff --exit-code || (echo "❌ Formatting failed but formatted file. Please add and commit again." && exit 1)'
        language: system
        pass_filenames: false
      - id: static-checks
        name: Static Checks
        entry: bash -c 'make static-checks || (echo "❌ Static checks failed. Please fix the issues and try again." && exit 1)'
        language: system
        pass_filenames: false
      - id: test
        name: Run Tests
        entry: bash -c 'make test || (echo "❌ Tests failed. Please fix the failing tests and try again." && exit 1)'
        language: system
        pass_filenames: false