# Project pack: wger @ 48e02bf

Facts about **wger** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> wger is a free fitness diary. Build workout routines from a library of exercises with pictures, log each session, and track your body weight and measurements over time. It also has meal plans and a calorie counter with a large food database from Open Food Facts. Use the free hosted site, or run it on your own computer or server so your health data stays yours. Phone apps for Android and iPhone can connect to either.

## Version and source
- Repository: https://github.com/wger-project/wger
- Pinned commit: `48e02bfe45e83b87781058261986cda88ff2e6d5`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/wger-project/wger/archive/48e02bfe45e83b87781058261986cda88ff2e6d5.zip
- Official docs: https://wger.readthedocs.io
- Live demo: https://wger.de. The project's own free hosted service with real users, not a throwaway demo. Make a free account to try it. Your data is stored there, so only enter what you're happy to keep on their server.
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just yourself or your household), you must offer them your source code under the same licence. Exercise and food data has its own Creative Commons licences, shown on each entry.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/wger-project/wger bespoke-wger
  cd bespoke-wger
  git checkout --detach 48e02bfe45e83b87781058261986cda88ff2e6d5
  # Prepare development requirements and local configuration first.
  # Setup notes: http://localhost:8000
  export DJANGO_SETTINGS_MODULE=settings.local_dev && uv sync --group dev && uv run wger bootstrap && uv run python manage.py runserver
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -ti --name wger.demo -p 8000:80 wger/demo
  # then open http://localhost:8000 and log in as admin / adminadmin.
  # This demo image wipes its data when updated; for real use, follow the docker compose setup in github.com/wger-project/docker
  ```

- Needs: Docker, or for development Python 3.12+ with uv and Node.js with npm
- Develop: `export DJANGO_SETTINGS_MODULE=settings.local_dev && uv sync --group dev && uv run wger bootstrap && uv run python manage.py runserver   # http://localhost:8000`
- Test: `uv run ./manage.py test --parallel auto`
- Check/lint: `uv run ruff check && uv run ruff format --check`
- Stack: python, javascript, html, scss (Django, Django REST Framework, Bootstrap 5, htmx, React components (@wger-project/react-components)). Difficulty for a non-developer with an AI: **moderate**. A large but conventional Django project split into apps (manager for routines, nutrition, weight, measurements, gallery, gym). Many screens, such as the routine and nutrition editors, come from a separate React package (wger-project/react), so changing them means working in that repository too.

## Customisation points (settings → extend → code)
- **profile-and-units** [settings]: Kilograms or pounds, weight rounding, language, time zone and email reminders for workouts and weigh-ins. → `User preferences (wger/core/models/profile.py)`
- **server-options** [settings]: Who can register, guest access, email, time zone and where to download exercises and foods from. → `Environment variables read in settings/main.py`
- **gym-mode** [settings]: Run it for a small gym, club or family, with trainers who can see their members' plans. → `Gym management pages (wger/gym/)`
- **api** [extend]: Read and write routines, logs, weight and meals from scripts, smartwatches or spreadsheets. → `REST API at /api/v2/, interactive docs at /api/v2/schema/ui on your instance (wger/urls.py)`
- **theme-and-templates** [code]: Colours, logo and layout of the server-rendered pages. → `wger/core/static/scss/main.scss (brand colours), wger/core/templates/template.html and navigation.html`
- **django-apps** [code]: New data, pages or API endpoints. Database changes need a Django migration. → `wger/manager/ (routines), wger/nutrition/, wger/weight/, wger/measurements/, wger/trophies/ (models/, views/, api/, migrations/)`
- **react-screens** [code]: The routine, nutrition and progress screens. Changing these means building that package too. → `Separate repository wger-project/react, loaded as @wger-project/react-components (see package.json)`

## Must keep working
- Existing routines, workout logs, weight entries, meal plans and photos. Back up the database and media folder first.
- Database changes need a new Django migration in the app's migrations/ folder; never edit old ones.
- User privacy between accounts, and the gym permissions for trainers and members.
- The /api/v2/ endpoints, which the official Android and iPhone apps rely on.

## Staying updatable
Profile settings, server options, gym mode and the REST API cover most personal needs without a fork. Keep code changes small and in their own app or template where you can. For the React screens, work in wger-project/react.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite for the demo and development; PostgreSQL in the recommended docker compose setup. Photos go in the media folder. Body weight, measurements, progress photos, birth date and diet are health data. Back up the database and the media folder before upgrades or code changes.
- Service: Email (SMTP) (optional, free with most providers): Workout and weigh-in reminders, account emails and password resets.
- Service: wger.de exercise and food data (optional, free): Downloads the shared exercise library and Open Food Facts ingredients into your own instance.
- Service: Redis and Celery (optional, free (self-hosted)): Background jobs and caching in the full docker compose setup, such as syncing exercises.
- Setting `SECRET_KEY` (**secret**: the person enters it themselves, never in chat): A long random string that protects logins. Set your own for any real install. Never paste it into an AI chat.
- Setting `SITE_URL`: The address you'll open wger at (used in emails and links). Default http://localhost:8000.
- Setting `TIME_ZONE`: Your time zone (default Europe/Berlin), e.g. Europe/London.
- Setting `ALLOW_REGISTRATION`: Defaults to true. Set to false so only people you add can sign up.
- Setting `ALLOW_GUEST_USERS`: Defaults to true. Set to false to stop visitors trying it without an account.
- Setting `ENABLE_EMAIL`: Turn on email (with EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD) for reminders.
- Set your own SECRET_KEY, turn off open registration and guest users, and use HTTPS before exposing it to the internet.
- This is health data. Think twice before sharing an instance, and back it up.
- Fitness and calorie suggestions are not medical advice.

---

# Customising wger

wger is a large Django project, and some of its main screens come from a separate React package. **Most personal adaptations are settings or the API.** Try levels 1 and 2 before touching code.

## Level 1: Settings (no code)
- **Your preferences:** kilograms or pounds, weight rounding, language, time zone, and email reminders for workouts and weigh-ins (fields in `wger/core/models/profile.py`).
- **Calorie goal:** fill in age, height, activity levels and let wger work out a daily target for your meal plan.
- **Routines:** build routines from the exercise library, with sets, reps and automatic weight progression rules.
- **Server options:** environment variables read in `settings/main.py`, e.g. `ALLOW_REGISTRATION`, `ALLOW_GUEST_USERS`, `TIME_ZONE`, `SITE_URL`, `ENABLE_EMAIL` and the `EMAIL_*` values.
- **Gym mode:** the Gyms pages (`wger/gym/`) let an admin add members and give trainers access to their plans. Useful for a club, coach or family.

## Level 2: Extend (no fork)
- **REST API** at `/api/v2/`, with interactive docs at `/api/v2/schema/ui` on your instance. Use it to copy logs into a spreadsheet, add weigh-ins from a smart scale, or build a home dashboard.
- **Phone apps:** the official Android and iPhone apps can point at your own server instead of wger.de.

## Level 3: Code
| Change | Where |
|---|---|
| Brand colours | `wger/core/static/scss/main.scss` (rebuild with `npm run build:css:sass`) |
| Page layout, menu, logo | `wger/core/templates/template.html`, `wger/core/templates/navigation.html` |
| Routines and workout logs | `wger/manager/` (`models/`, `views/`, `api/`) |
| Food, meal plans, calories | `wger/nutrition/` |
| Weight, measurements, photos, trophies | `wger/weight/`, `wger/measurements/`, `wger/gallery/`, `wger/trophies/` |
| New data | the app's `models/` + `uv run python manage.py makemigrations` |
| Text | `wger/locale/` (translations come from Weblate) |
| Routine, nutrition and progress screens | separate repository `wger-project/react`, used here as `@wger-project/react-components` |

## Running locally
- **Just try it:** `docker run -ti --name wger.demo -p 8000:80 wger/demo`, then open http://localhost:8000 and log in as `admin` / `adminadmin`. This image loses its data on update.
- **Use it for real:** follow the docker compose setup in github.com/wger-project/docker (PostgreSQL, Redis, Celery, persistent volumes).
- **Develop:**
  1. Install Python 3.12+, uv and Node.js.
  2. `export DJANGO_SETTINGS_MODULE=settings.local_dev`
  3. `uv sync --group dev`
  4. `uv run wger bootstrap` (database, starter data, CSS).
  5. `uv run python manage.py runserver` and open http://localhost:8000.
- **Check:** `uv run ./manage.py test --parallel auto`, `uv run ruff check`, `uv run ruff format --check`.

## Pitfalls
- Back up the database and media folder first. Training history and progress photos can't be recreated.
- The demo image is not for real data.
- Don't change the `/api/v2/` responses the phone apps depend on.
- Many screens are React. If the page you want to change isn't in a Django template, it lives in `wger-project/react`.
- Calorie and training suggestions are not medical advice.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/wger/48e02bf/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/wger/48e02bf/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/wger/48e02bf/r2/SKILL.md)