# Deployment Guide This guide covers deploying the Wizamart platform to production environments. !!! tip "New to deployment?" Start with the [Infrastructure Guide](infrastructure.md) for a complete overview of architecture options. ## Deployment Options | Option | Best For | Guide | |--------|----------|-------| | **Traditional VPS** | Direct server access, debugging | [Production Guide](production.md) | | **Docker Compose** | Consistent environments, easy rollbacks | [Docker Guide](docker.md) | | **Managed Services** | Minimal ops, small teams | See [Infrastructure Guide](infrastructure.md#option-3-managed-services-minimal-ops) | ## Prerequisites - Python 3.11+ - PostgreSQL 15+ (required - SQLite not supported) - Redis (required for Celery background jobs) - Docker (for development database) - Tailwind CSS CLI (standalone binary) ## Environment Configuration ### Required Environment Variables ```bash # Application APP_ENV=production SECRET_KEY= DEBUG=false # Database DATABASE_URL=postgresql://user:password@host:5432/wizamart # Security ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com CORS_ORIGINS=https://yourdomain.com # Email SMTP_HOST=smtp.provider.com SMTP_PORT=587 SMTP_USER=your-email SMTP_PASSWORD=your-password EMAIL_FROM=noreply@yourdomain.com # Letzshop Integration LETZSHOP_API_ENDPOINT=https://letzshop.lu/graphql ENCRYPTION_KEY= # Optional: Redis REDIS_URL=redis://localhost:6379/0 ``` ### Generating Secrets ```bash # Generate SECRET_KEY python -c "import secrets; print(secrets.token_urlsafe(64))" # Generate ENCRYPTION_KEY (Fernet) python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" ``` ## Deployment Steps ### 1. Clone and Setup ```bash git clone cd wizamart # Install dependencies uv sync --frozen # Activate virtual environment source .venv/bin/activate ``` ### 2. Database Setup ```bash # Run migrations alembic upgrade head # Initialize production data python scripts/init_production.py ``` ### 3. Static Assets ```bash # Build Tailwind CSS using standalone CLI # Download from: https://github.com/tailwindlabs/tailwindcss/releases tailwindcss -i ./static/shared/css/input.css -o ./static/shared/css/tailwind.output.css --minify # Same for admin and vendor CSS tailwindcss -i ./static/admin/css/tailwind.css -o ./static/admin/css/tailwind.output.css --minify tailwindcss -i ./static/vendor/css/tailwind.css -o ./static/vendor/css/tailwind.output.css --minify ``` ### 4. Run Application #### Using Uvicorn (recommended) ```bash uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4 ``` #### Using Gunicorn with Uvicorn workers ```bash gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 ``` ## Reverse Proxy Configuration ### Nginx Example ```nginx server { listen 80; server_name yourdomain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name yourdomain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location /static { alias /path/to/app/static; expires 30d; add_header Cache-Control "public, immutable"; } } ``` ## Docker Deployment ### Dockerfile ```dockerfile FROM python:3.11-slim WORKDIR /app # Install uv and download Tailwind CLI RUN pip install uv && \ curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64 && \ chmod +x tailwindcss-linux-x64 && \ mv tailwindcss-linux-x64 /usr/local/bin/tailwindcss # Copy dependency files COPY pyproject.toml uv.lock ./ # Install dependencies RUN uv sync --frozen --no-dev # Copy application COPY . . # Build static assets RUN tailwindcss -i ./static/shared/css/input.css -o ./static/shared/css/tailwind.output.css --minify EXPOSE 8000 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"] ``` ### Docker Compose ```yaml version: '3.8' services: web: build: . ports: - "8000:8000" environment: - DATABASE_URL=postgresql://postgres:password@db:5432/wizamart depends_on: - db db: image: postgres:14 volumes: - postgres_data:/var/lib/postgresql/data environment: - POSTGRES_DB=wizamart - POSTGRES_PASSWORD=password volumes: postgres_data: ``` ## Health Checks The application provides health check endpoints: - `GET /health` - Basic health check - `GET /health/ready` - Readiness check (includes DB) ## Monitoring ### Logging Logs are output to stdout in JSON format for production: ```bash # View logs docker logs -f wizamart-web # Or with systemd journalctl -u wizamart -f ``` ### Metrics Consider integrating: - Prometheus for metrics collection - Grafana for visualization - Sentry for error tracking ## Backup Strategy ### Database Backups ```bash # PostgreSQL backup pg_dump -U postgres wizamart > backup_$(date +%Y%m%d).sql # Automated daily backups (cron) 0 2 * * * pg_dump -U postgres wizamart | gzip > /backups/wizamart_$(date +\%Y\%m\%d).sql.gz ``` ## Rollback Procedure ```bash # Rollback database migration alembic downgrade -1 # Rollback to specific revision alembic downgrade ``` ## Troubleshooting ### Common Issues 1. **Database connection errors** - Verify DATABASE_URL format - Check PostgreSQL is running - Verify network connectivity 2. **Static files not loading** - Rebuild Tailwind CSS - Check Nginx static file configuration - Verify file permissions 3. **Email not sending** - Verify SMTP credentials - Check firewall allows outbound SMTP - Test with `python scripts/test_email.py` ### Debug Mode For troubleshooting, temporarily enable debug mode: ```bash DEBUG=true uvicorn app.main:app --reload ``` **Warning**: Never use debug mode in production with real traffic.