Installation Guide

Setting Up FitPulse On Your Machine

Set aside about twenty minutes. Nothing here is complicated, but do the steps in order — skipping the seed commands is the number one reason people message us saying "the dashboard is empty."

Prerequisites

1. Python 3.10 or newer. Open a terminal and type python --version. If you see 3.10, 3.11, 3.12 or 3.13, you're good. If it says 2.7 or "not recognized," go to python.org, download the latest 3.x installer, and on Windows tick the "Add Python to PATH" checkbox during install. That checkbox matters more than anything else on the screen.
2. pip. Comes bundled with Python. Check with pip --version.
3. A code editor. VS Code is fine. Notepad is not.
4. Optional — a Groq API key. Sign up free at console.groq.com and create one. Skip this if you just want the app running; the AI Coach page will show a fallback message instead.
5. Optional — Redis. Only needed if you turn on Celery background tasks. You do not need it to run the app or to demo it.

Step 1 — Open the project folder in a terminal

Extract the zip you downloaded. Right-click inside the extracted folder and open a terminal there, or cd into it manually. You should see manage.py when you run dir on Windows or ls on macOS and Linux. If you don't see it, you're one folder too high — go one level deeper.

Step 2 — Create and activate a virtual environment

This keeps FitPulse's packages separate from everything else on your system.

python -m venv venv

Now activate it. The command depends on what you're using:

• Windows PowerShell: venv\Scripts\Activate.ps1
• Windows Git Bash: source 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 from here on assumes you can see that.

Step 3 — Install the dependencies

pip install -r requirements.txt

This pulls in Django 5.2, Django REST Framework, django-axes, django-htmx, django-ratelimit, the Groq client, WeasyPrint, Celery, python-decouple and pytest-django. Takes a couple of minutes on decent internet. Grab water.

Step 4 — Set up your environment file

Copy the example file:

cp .env.example .env

On Windows PowerShell use copy .env.example .env instead.

Open .env in your editor. You must set SECRET_KEY. Generate a proper one with:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Copy the string it prints and paste it after SECRET_KEY=. No quotes needed.

If you have a Groq key, paste it into GROQ_API_KEY= as well. Leave EMAIL_HOST blank — that makes Django print verification emails to your terminal instead of trying to send real ones, which is exactly what you want during development.

Step 5 — Build the database

python manage.py migrate

This creates db.sqlite3 and all the tables. You should see a long list of "Applying..." lines ending in OK.

Step 6 — Seed the reference data

Run these five, one at a time. Skipping any one of them leaves a section of the app empty.

python manage.py seed_exercises
python manage.py seed_workout_templates
python manage.py seed_foods
python manage.py seed_recipes
python manage.py seed_challenges

Step 7 — Seed the demo accounts (do this, seriously)

python manage.py seed_demo_data

This creates four fully onboarded users with roughly ten logged workout sessions each, personal records, a week of meals and water, eight weeks of body measurements, and community activity linking them together. It's safe to run more than once. Without it your charts are blank lines and your feed is empty, which looks bad in a demo.

Step 8 — Create your own admin account

python manage.py createsuperuser

Enter an email and a password. The password won't show as you type it — that's normal, keep typing.

Step 9 — Run it

python manage.py runserver

Open http://127.0.0.1:8000/ in your browser. That's the landing page. Then go to http://127.0.0.1:8000/accounts/login/ and log in with:

• Email: demo@fitpulse.app
• Password: Demo@12345

Django admin lives at http://127.0.0.1:8000/admin/ with the superuser you just created.

Common Issues And How To Fix Them

"cannot load library 'gobject-2.0-0'" when exporting a PDF

This is WeasyPrint asking for GTK, and it's the single most common problem on Windows. Download the GTK3 runtime installer (search for "gtk3-runtime win64 installer" — the tschoonj GitHub release is the standard one), install it, then close your terminal completely and open a fresh one before running the server again. Restarting the terminal matters; the PATH change won't apply to the window you already have open. On macOS use brew install pango. On Ubuntu use sudo apt install libpango-1.0-0 libpangoft2-1.0-0.

"SECRET_KEY setting must not be empty"

Either you forgot Step 4, or your .env file got saved as .env.txt. Windows loves doing this quietly. Turn on file extension display in Explorer, check the actual filename, and rename it if needed.

The verification email never arrives

It's not supposed to. With EMAIL_HOST blank, Django prints the whole email into the terminal running runserver. Scroll up in that terminal, find the line containing /accounts/verify/, copy that full URL and paste it into your browser. Account verified.

Account locked after a few failed logins

That's django-axes doing its job. Run python manage.py axes_reset and try again.

"port 8000 is already in use"

Another server is running somewhere. Either close it or just use a different port: python manage.py runserver 8001.

How To Verify Everything Actually Works

Run the test suite first:

python -m pytest -q

All 87 tests should pass. If they do, your setup is correct and you can stop worrying.

Then do a quick manual check as demo@fitpulse.app:

1. Dashboard loads with numbers filled in, not zeros
2. Exercises page shows a long list and the search box filters as you type
3. Workouts to History shows past sessions with sets logged
4. Nutrition tracker shows meals and macro totals for the day
5. Progress page renders charts with an actual trend line, and the PDF export button downloads a file
6. Community feed shows posts from the other demo users, and clicking like updates the count without reloading the page
7. AI Coach either streams a real reply or shows the fallback message, depending on your API key

All seven working means you're done. Go rehearse your viva.