wger Deployment and Usage Guide

1. Prerequisites

Runtime & Database

Docker and Docker Compose (recommended for production)
Python 3.9+ (for development)
PostgreSQL 12+ or SQLite (development only)
Redis (optional, for caching and Celery tasks)

Tools

Git (to clone the repository)
pip (Python package manager)
Node.js & npm (for frontend assets, development only)

Accounts (Optional)

Open Food Facts API (for nutrition database integration)
Email service (for user registration and password reset functionality)

2. Installation

Clone the Repository

git clone https://github.com/wger-project/wger.git
cd wger

Docker Installation (Production)

The recommended way to deploy wger is using the official Docker setup:

# Clone the docker repository
git clone https://github.com/wger-project/docker.git
cd docker

# Start the services
docker compose up -d

This will set up:

PostgreSQL database
wger application server
Nginx reverse proxy
Celery worker (for background tasks)
Redis (for caching and message broker)

Manual Installation (Development)

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt  # For development

# Install frontend dependencies
npm install

3. Configuration

Environment Variables

Create a .env file in the project root with the following variables:

# Database configuration
DATABASE_URL=postgres://wger:wger@localhost:5432/wger
# or for SQLite (development):
# DATABASE_URL=sqlite:///database.sqlite

# Django settings
SECRET_KEY=your-secret-key-here
DEBUG=False  # Set to True for development
ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.com

# Email configuration (optional)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-password
EMAIL_USE_TLS=True
DEFAULT_FROM_EMAIL=wger@your-domain.com

# Cache configuration
REDIS_URL=redis://localhost:6379/0

# Open Food Facts API
OFF_API_KEY=your-api-key-optional

Django Settings

The main configuration file is wger/settings.py. Key settings to review:

# Internationalization
LANGUAGES = [
    ('en', 'English'),
    ('de', 'Deutsch'),
    # ... other languages
]

# Static and media files
STATIC_URL = '/static/'
MEDIA_URL = '/media/'
STATIC_ROOT = os.path.join(BASE_DIR, 'static')
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

# API settings
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.TokenAuthentication',
    ]
}

4. Build & Run

Development Server

# Apply database migrations
python manage.py migrate

# Create a superuser
python manage.py createsuperuser

# Load initial exercise and ingredient data
python manage.py load-exercise-data
python manage.py load-ingredient-data

# Collect static files
python manage.py collectstatic

# Compile translations
python manage.py compilemessages

# Run development server
python manage.py runserver

Access the application at http://localhost:8000

Production Build with Docker

# Build and start all services
docker compose up -d --build

# View logs
docker compose logs -f

# Run management commands
docker compose exec wger python manage.py migrate
docker compose exec wger python manage.py load-exercise-data
docker compose exec wger python manage.py createsuperuser

Background Workers

For email sending and other asynchronous tasks:

# Start Celery worker (development)
celery -A wger worker -l INFO

# Start Celery beat for scheduled tasks
celery -A wger beat -l INFO

5. Deployment

Recommended Platforms

Self-Hosted with Docker (Recommended)

Use the provided docker-compose.yml on any VPS (DigitalOcean, Linode, AWS EC2, etc.)
Add a reverse proxy (Nginx or Traefik) with SSL certificates
Set up regular database backups

Traditional VPS

Ubuntu/Debian server with Python 3.9+
PostgreSQL database
Gunicorn or uWSGI as application server
Nginx as reverse proxy
Systemd for process management

Platform as a Service

Heroku: Use PostgreSQL addon, set up buildpacks for Python
Railway: Supports Docker and PostgreSQL natively
Fly.io: Good for Docker-based deployments

Deployment Steps (Docker on VPS)

# 1. Clone and configure
git clone https://github.com/wger-project/docker.git
cd docker
# Edit docker-compose.yml and .env as needed

# 2. Start services
docker compose up -d

# 3. Set up reverse proxy (Nginx example)
# Install Nginx and Certbot
sudo apt install nginx certbot python3-certbot-nginx

# Configure Nginx site
sudo nano /etc/nginx/sites-available/wger

# 4. Obtain SSL certificate
sudo certbot --nginx -d your-domain.com

Scaling Considerations

Use PostgreSQL connection pooling (PgBouncer)
Configure Redis for session and cache storage
Set up multiple Celery workers for heavy background tasks
Use CDN for static and media files (AWS S3, Cloudflare)

6. Troubleshooting

Common Issues

Database Migration Errors

# Reset migrations (development only)
python manage.py migrate --fake
python manage.py migrate

# Or start fresh
python manage.py flush
python manage.py migrate

Static Files Not Loading

# Collect static files
python manage.py collectstatic --noinput

# Check permissions
chmod -R 755 static/

Email Not Sending

Verify SMTP settings in .env
Check if port 587 is open (for TLS)

For development, use console backend:

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

Exercise/Ingredient Data Not Loading

# Load data with specific language
python manage.py load-exercise-data en
python manage.py load-ingredient-data en

# Check database permissions
python manage.py check

Docker Container Issues

# Check container logs
docker compose logs wger

# Restart services
docker compose restart

# Rebuild containers
docker compose up -d --build

# Check database connectivity
docker compose exec db psql -U wger -d wger

API Authentication Problems

Ensure TokenAuthentication is enabled in settings

Generate API token for user:

python manage.py drf_create_token <username>

Or through the web interface at /api/v2/token/

Performance Issues

Enable caching in settings:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379/1',
    }
}

Use database connection pooling
Optimize PostgreSQL configuration

Getting Help

Check the logs: docker compose logs -f or journalctl -u your-service
Verify all services are running: docker compose ps
Consult the documentation: https://wger.readthedocs.io
Join the Discord community: https://discord.gg/rPWFv6W
File issues on GitHub: https://github.com/wger-project/wger/issues

How to Deploy & Use wger