MacFAST Django backend

REST API for the MacFAST project built with the Django REST framework, deployed on the university's network at https://macfast.ca.

Getting Started

1. Clone the Repository:

   git clone https://github.com/McMaster-FAST/backend.git
   cd backend

2. Create and Activate Virtual Environment: Using uv:

   uv venv
   source .venv/bin/activate

   (Or with standard venv: python -m venv .venv and source .venv/bin/activate)

3. Install Dependencies:

   uv sync

Configuration

The project uses a .env file for managing secrets and environment-specific settings. System environment variables take precedence over values loaded from .env.

1. Create your Environment File: Copy the sample file to create your local environment file. This .env file is in .gitignore and should never be committed to source control.

   cp sample.env .env

2. Edit your .env File: Open the .env file in your editor and fill in the required values. The comments in sample.env will guide you.

Running the Server

1. Apply Database Migrations:

   uv run manage.py migrate

2. Run the Development Server:

   uv run manage.py runserver

   The server will start on http://localhost:8000/.

Migration History Repair (one-off)

If you hit an error like: InconsistentMigrationHistory: analytics.0007 ... applied before analytics.0006 ..., run:

uv run manage.py repair_analytics_migration_history
uv run manage.py migrate

To preview without changing anything:

uv run manage.py repair_analytics_migration_history --dry-run

Loading Mock Data

If you are doing development and need mock data to test with you can run

To load mock data only if the database is empty:

uv run manage.py load_fixtures

or to load all mock data unconditionally:

uv run manage.py loaddata mock/data.json

To unload mock data:

uv run manage.py unload_fixtures

Health Check

You can test that the server is running correctly by hitting the API's health check "ping" endpoint.

Endpoint: GET /api/core/ping/

Example using a Browser: With the server running, visit the following URL in your browser: http://localhost:8000/api/core/ping/

Expected Response

{
  "message": "pong"
}

Running Tests

You can run the unit tests for the project by running the following command:

uv run pytest

or run tests for a specific test file (e.g. the OIDC backend tests):

uv run pytest core/tests/test_oidc_backend.py