smiteshz / backend

Slick Telemetry backend written in python and fastapi with fastf1

backend

Slick Telemetry backend written in python with fastf1.

Table of Contents:

• Setting up the project
  • What you'll need
• Development
  • Environment variables
  • Python virtual environment
    • Installing dependencies
    • Virtual environment sanity check
    • Poe the Poet poetry plugin
    • Installing git hooks
  • Running the project
  • Running tests
  • Docker
    • App only
    • With Supabase
  • Interactive API docs
  • Contribution Guidelines
• Deployment

Setting up the project

What you'll need

• VSCode / Pycharm
• Python 3.12 (Please check pyproject.toml for the latest supported python version)
• Poetry for dependency management
• Docker Desktop [OPTIONAL]

Development

Environment variables

• In project root, create a copy of .env.example as .env.

Python virtual environment

Installing dependencies

poetry config virtualenvs.in-project true # OPTIONAL
poetry install --sync --no-root --with dev,lint,test

Note: Ensure that the python interpreter in your IDE is set to the newly created virtual environment by poetry. If you have not modified poetry configuration, you can find the virtual environment location as stated here.

Virtual environment sanity check

• Your IDE should activate the virtual environment for you automatically.
• If it doesn't, you can follow either of these steps:
  • Check the path of poetry env - poetry env info.
  • Set poetry python interpreter path in VS Code OR
  • Run poetry shell OR
  • Execute the /Scripts/Activate script from the virtual environment located here.

Poe the Poet poetry plugin

poetry self add 'poethepoet[poetry_plugin]'

1. Check available tasks:

   poetry poe

2. Execute a task:

   poetry poe <task-name>

   For example, running the project formatters:

   poetry poe formatters

Installing git hooks

poetry poe git-hooks-setup

Running the project

• Open up a terminal in your IDE.
• Run python run.py to start the server.
• Open your browser at http://localhost:8081.

Running tests

poetry poe tests

Docker

In /docker, create a copy of .env.example as .env.

App only

• Build image

  docker build --file Dockerfile.dev --tag backend-dev .

• Run container

  docker run --name backend-dev --publish 8081:8081 backend-dev --detach

• Open your browser at http://localhost:8081.

With Supabase

• Bring up the services

  cd docker
  docker compose --file compose.dev.yaml up --detach

• Open your browser at
  • http://localhost:8081 for app
  • http://localhost:8000 for supabase dashboard
  • Username: supabase
  • Password: this_password_is_insecure_and_should_be_updated

For other docker commands, see useful_commands.md

Interactive API docs

• Once the server is running, open your browser at http://localhost/docs.
• Alternate docs can be found at http://localhost/redoc, provided by redoc.

Contribution Guidelines

• NEVER MERGE YOUR OWN CODE; ALWAYS RAISE A PR AGAINST dev!
• Follow conventional commit format when authoring commit messages.
• Always pull latest changes
  • There are several developers working on this project. Always pull/pull-rebase the latest, as necessary, from the branch you intend to commit your changes to.
  • If there are local staged/unstaged changes, please stash or discard them as appropriate and then use git pull --rebase.
  • If you don't want to use git CLI, to simplify these operations and have a visual representation of the git tree, we suggest to use a git GUI -
    • Github Desktop (free)
    • GitKraken (paid)
    • Fork (paid)
    • GitLens (freemium)
    • Git Graph (free)
• Branches:
  • main is the production mainline.
  • dev is the development line (default branch).
• PR merge strategy on Github
  • Code should flow in the following direction through branches:

    feature/bug fix -> dev -> main
    

  • We'll be keeping a linear commit history and so using a combination of Rebase and merge and Squash and merge merge strategies.
  • Use Rebase and merge as default to ensure all commits from the branch to be merged are brought in individually to the target branch.
  • Squash and merge may be used ONLY when bringing in changes from a feature/bug fix branch into dev.
  • To maintain linear commit history, ensure to use push force when:
    • Bringing dev on the same commit as main (ie rebasing dev onto main).
  • More information on git rebase.
  • More information on PR merge strategies.
• Jira issue linking
  • Commits and PRs must be linked to a Jira issue.
  • To do so, include the Jira issue key in the PR title and/or the commit message after the conventional commit type.
  • More information on Jira smart commits.

Deployment

// TODO