Quiz Backend

The backend for a generic mobile-friendly quiz engine created using FastAPI and MongoDB! The frontend can be found here.

Table of Contents:

• Installation
  • Local DB Setup
    • Linux Systems
    • Mac Systems
  • Virtual Environment Setup
• Running locally
• Deployment
• Tests

Installation

Local DB Setup

Linux Systems

The following steps are for a Linux system.

• To run the backend locally, you would need to setup a local instance of mongodb. The offical instructions here are good and simple enough to follow. Those steps are also listed down below.

  • Import the public key used by the package management system. Issue the following command to import the MongoDB public GPG Key from here:

    curl -fsSL https://pgp.mongodb.com/server-6.0.asc | \
    sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg \
    --dearmor
    

  • From a terminal, install gnupg if it is not already available:

    sudo apt-get install gnupg
    

  • Create a list file for MongoDB. Create the list file /etc/apt/sources.list.d/mongodb-org-6.0.list for your version of Ubuntu. To check the Ubuntu version the host is running, open a terminal or shell on the host and execute

    lsb_release -dc
    

    According to the version, run the respective code on the terminal. The below code is for the Ubuntu version 22.04(Jammy), if you have a different version running then replace the the below command according to your version from here.

    • Ubuntu 22.04 (Jammy)

      echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
      

  • Reload local package database. Issue the following command to reload the local package database:

    sudo apt-get update
    

  • Install the MongoDB packages Install the latest stable version of MongoDB

    sudo apt-get install -y mongodb-org
    

Mac Systems

The following steps are for a Mac system.

• To run the backend locally, you would need to setup a local instance of mongodb. The offical instructions here are good and simple enough to follow. Those steps are also listed down below.

  • Install the Xcode command-line tools

    xcode-select --install

  • Make sure you have homebrew installed. If not, go here
  • Download the official Homebrew formula for MongoDB

    brew tap mongodb/brew

  • Update Homebrew and all existing formulae

    brew update

  • Install MongoDB

    brew install mongodb-community@6.0

  • Make sure mongosh (your mongo shell) is added to the PATH. To test it out, type mongosh in your terminal and press enter. It should NOT give any error.

Virtual Environment Setup

• Python 3.12 is required. Create a virtual environment:

  python3.12 -m venv venv

• Activate the environment:

  source venv/bin/activate

• Install the dependencies:

  pip install -r app/requirements.txt

• Install pre-commit:

  pip install pre-commit
  

• Set up pre-commit:

  pre-commit install
  

• Copy .env.example to .env and set all the environment variables as mentioned in docs/ENV.md. The default value points to a local MongoDB instance — no changes needed for local development.

Running locally

For Linux machines, simply run the below in the terminal:

chmod +x startServerLinux.sh
./startServerLinux.sh

For Mac Simply run:

chmod +x startServerMac.sh
./startServerMac.sh

You should see a message like:

Starting the mongod process
Service `mongodb-community` already started, use `brew services restart mongodb-community` to restart.
Starting the server now
INFO:     Will watch for changes in these directories: ['/Users/deepansh/Documents/Work/repos/quiz-backend/app']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [38899] using statreload
INFO:     Started server process [38901]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Use http://127.0.0.1:8000 as the base URL of the endpoints and navigate to http://127.0.0.1:8000/docs to see the auto-generated docs! 💃

Deployment

The backend is deployed on ECS Fargate (ARM64/Graviton) for both testing and production environments. Deployment is automated via GitHub Actions:

• Testing (quiz-backend-testing.avantifellows.org): deploys on CI success on main via .github/workflows/deploy_ecs_testing.yml
• Production (quiz-backend.avantifellows.org): deploys on CI success on release via .github/workflows/deploy_ecs_prod.yml

Infrastructure is managed by Terraform in terraform/testing/ and terraform/prod/. Configure ECS application variables in the corresponding gitignored terraform.tfvars, using terraform.tfvars.example as the template. See docs/ENV.md for details.

Tests

Tests run against a real MongoDB instance (local or CI service) and clear its quiz database. Make sure MongoDB is running locally, MONGO_AUTH_CREDENTIALS points to a disposable test instance, and opt in to the reset only for the test command:

ALLOW_TEST_DATABASE_RESET=1 pytest

Do not add ALLOW_TEST_DATABASE_RESET to .env.

Logs

Application logs are configured in app/logger_config.py and output to stdout/stderr. On ECS Fargate, logs are sent to CloudWatch Logs automatically.