wger

wger is a self‑hostable, feature‑rich fitness and nutrition manager written in Python using the Django web framework. The core domain model revolves around exercises, workout plans, meals, and user‑generated progress data, all exposed through a well‑documented REST API. The application is deliberately modular: the front‑end uses Django’s templating engine for the web UI, while a separate Flutter mobile app consumes the same API, ensuring consistency across platforms. The codebase follows Django’s conventional project layout (wger/core, wger/exercises, etc.), making it straightforward for developers familiar with Django to navigate and extend.

Architecture & Technical Stack

• Language: Python 3.10+
• Framework: Django (latest LTS), Django REST Framework for the API layer
• Database: PostgreSQL is recommended (default in Docker images), with optional support for SQLite during development
• Caching: Redis is used for session and cache backends, improving API throughput
• Search & Full‑text: PostgreSQL’s native full‑text search powers the exercise wiki and food database queries
• Containerization: A multi‑service docker‑compose.yml bundles the web server, PostgreSQL, Redis, and a Celery worker for background tasks (e.g., email reminders)
• Static Assets: Managed via Django’s collectstatic, with optional CDN support
• Internationalization: Translations are maintained through Weblate, integrated into the Django i18n framework

The application follows a classic MVC pattern: models represent exercises, workouts, meals; views (class‑based) handle HTTP requests and serialize data; templates provide a responsive UI. The REST API exposes CRUD endpoints for all primary resources, supports pagination, filtering, and search parameters, and follows HATEOAS principles for discoverability.

Core Capabilities & APIs

• Workout Management: Create custom routines with automatic weight progression (e.g., linear or exponential), schedule them, and log completed sets/reps
• Nutrition Tracking: Import ingredients from Open Food Facts; calculate macro‑and micronutrient totals per meal or week
• Progress Logging: Upload photos, record body weight, and attach notes; the API supports file uploads via multipart forms
• Exercise Wiki: Read‑only and write‑capable endpoints for exercises, allowing contributors to add new movements or update existing ones
• Multi‑User & Gym Mode: User accounts can be grouped into gyms; admins can manage memberships and view aggregated statistics
• Webhook Support: Developers can register webhooks on workout or meal events, enabling integration with external services (e.g., Slack notifications)
• Extensibility: The wger/core app exposes a plugin API; developers can create Django apps that hook into signals (e.g., post_save on a workout) to trigger custom logic

Deployment & Infrastructure

Deploying wger is as simple as pulling the official Docker image and running docker compose up -d. The provided docker-compose.yml defines:

1. web – Django gunicorn server
2. db – PostgreSQL container
3. redis – Redis cache and Celery broker
4. celery – Background task worker (e.g., sending reminders)
5. nginx – Optional reverse proxy for HTTPS termination

The stack is horizontally scalable: multiple web replicas can be spun up behind a load balancer, while the database can be migrated to a managed PostgreSQL instance. For high‑availability, Redis can run in cluster mode. The application is stateless aside from session storage, making it ideal for Kubernetes deployments or cloud‑native environments.

Integration & Extensibility

The REST API follows standard conventions (/api/v1/exercises/, /api/v1/workouts/), enabling developers to consume it with any HTTP client. Authentication is token‑based (JWT or session cookies), and the API supports OAuth scopes for fine‑grained access control. Webhooks can be configured per user, with payloads that include the event type and resource data. For deeper integration, developers can tap into Django signals or create custom management commands that run against the database directly.

The plugin system is intentionally lightweight: any Django app can register a ready() hook in its apps.py to modify URLs, add template tags, or listen to signals. This allows gym operators to build custom dashboards, analytics tools, or third‑party authentication backends without touching the core code.

Developer Experience

• Documentation: Comprehensive docs are hosted on ReadTheDocs, covering API usage, deployment, and contribution guidelines. Inline docstrings and type hints aid IDE autocomplete.
• Community: The project has an active GitHub issue tracker, a Weblate translation community, and regular contributors. Licensing under AGPL‑3.0 ensures that any derivative work remains open source, encouraging collaboration.
• Testing: The repo includes extensive unit and integration tests (coverage > 80%), run automatically via GitHub Actions. Developers can easily add new test cases in the tests/ directories.
• Configuration: Settings are split into environment‑specific files (settings/base.py, settings/production.py), allowing developers to override defaults via environment variables or a .env file.

Use Cases

1. Gym Management – A small gym can host wger to provide members with workout plans, track progress, and manage class schedules. 2