Installation Guide

Before You Start

Three things need to exist on your machine before any of this works.

1. Python 3.10 or newer. Grab it from python.org if you don't have it. On Windows, tick the "Add Python to PATH" checkbox during install — skipping that box is responsible for roughly half the setup problems students message us about. Check it worked by opening a terminal and running python --version.
2. A code editor. VS Code is fine. Anything is fine.
3. A Groq API key (optional). Sign up free at console.groq.com and copy your key. Skip this for now if you just want to see the app run — the scanner works without it.

Step 1: Unzip and Create a Virtual Environment

Extract the project folder somewhere sensible. Not inside OneDrive, not on the Desktop with a folder name containing spaces. Open a terminal inside that folder and run:

python -m venv venv

Now activate it. Windows:

venv\Scripts\activate

macOS or Linux:

source venv/bin/activate

You'll know it worked because (venv) shows up at the start of your terminal line. Every command after this must be run with that visible.

Step 2: Install the Dependencies

pip install -r requirements.txt

This pulls in Django, scikit-learn, the Groq client, WeasyPrint and the rest. Takes a minute or two depending on your connection. scikit-learn is the big one.

Step 3: Set Up Your Environment File

There's a file called .env.example in the project root. Make a copy of it and rename the copy to .env — just .env, no other extension. Open it and fill in:

DJANGO_SECRET_KEY=any-long-random-string-you-want
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
GROQ_API_KEY=paste-your-key-here

Leave GROQ_API_KEY blank if you don't have one yet. Never commit this file to GitHub — it's already in .gitignore for exactly that reason.

Step 4: Create the Database

python manage.py migrate

This builds the SQLite tables. You'll see a wall of green "OK" lines. That's the good outcome.

Step 5: Train the Severity Model

The trained model file isn't shipped in the repo, so you generate it yourself:

python train_model.py

This creates training_data.csv in the project root and scanner/ml_model/severity_classifier.pkl, then prints a classification report and a feature importance table. Screenshot that output. Seriously — it's going straight into your project report and you'll be annoyed if you have to re-run the script just to get the numbers back.

Takes a few seconds. It's deterministic given the same seed, so re-running gives you the same model.

Step 6: Install GTK3 for PDF Reports (Windows Only)

WeasyPrint needs the GTK3 runtime libraries to turn HTML into a PDF, and pip cannot install those on Windows. Run this in a normal terminal:

winget install --id tschoonj.GTKForWindows -e

Close and reopen your terminal afterwards so the new PATH entries get picked up. On macOS you'd install the equivalent libraries through Homebrew, and on Linux through apt — check the WeasyPrint install docs for the exact package names for your distro.

Skipping this step doesn't break the app. Every other feature keeps working; only the "Download PDF Report" button will show an error telling you what's missing.

Step 7: Run It

python manage.py runserver

Open http://127.0.0.1:8000/ in your browser. Dark terminal-style homepage with a code input box means you're done.

Step 8: Confirm Everything Actually Works

1. On the homepage, click one of the "Try a sample" buttons. It loads a deliberately vulnerable snippet.
2. Hit scan. You should land on a results page with a security score, a severity breakdown, and expandable finding cards with highlighted code.
3. Expand a finding. If you added a Groq key, the explanation reads like a person wrote it. If you didn't, you'll see the generic fallback text — that's expected, not a bug.
4. Click "Download PDF Report". A PDF should save. If it errors, go back to Step 6.
5. Optional: sign up, run another scan, then visit /history/. Your scan should be listed there with a re-download link.

All five working means the full pipeline is live.

When Things Go Wrong

"ModuleNotFoundError" for Django or sklearn. Your virtual environment isn't active. Look for (venv) in your terminal prompt — if it's not there, activate it again and re-run.

PDF download throws a WeasyPrint or cairo error. GTK3 is missing or your terminal is still using the old PATH. Run the winget command from Step 6, then fully close the terminal and start a fresh one.

Every finding comes back with the same severity. The severity_classifier.pkl file probably isn't there, so the app has fallen back to a simple rule-based heuristic. Run python train_model.py again and check that the file appears under scanner/ml_model/.

Explanations look generic and identical across findings. Your Groq key is blank, wrong, or out of quota. Check the value in .env, then restart the server — Django reads environment variables at startup, not on every request.

Upload gets rejected. File limit is 500KB and only .py, .js and .php are accepted. Paste the relevant section instead of uploading the whole file.