backend/ENV_SETUP.md

Environment Configuration Guide

Overview

Ce projet utilise des variables d'environnement pour la configuration. Toutes les variables ont été centralisées dans des fichiers .env.

Setup Instructions

1. Copy the example file

cp .env.example .env

2. Edit the .env file with your values

Required for Development:

• GOOGLE_CLIENT_ID - Votre Google OAuth2 Client ID
• GOOGLE_CLIENT_SECRET - Votre Google OAuth2 Client Secret
• JWT_SECRET_KEY - Clé secrète pour JWT (générez une clé sécurisée)

Required for Production:

• Database credentials (SPRING_DATASOURCE_*)
• Email configuration (SPRING_MAIL_*)
• Production OAuth2 redirect URI
• Secure JWT secret key

Environment Profiles

Development (SPRING_PROFILES_ACTIVE=dev)

• Uses H2 in-memory database
• Uses Mailtrap for email testing
• CSRF disabled
• Flyway disabled

Production (SPRING_PROFILES_ACTIVE=prod)

• Uses MySQL database
• Uses production SMTP server
• CSRF enabled
• Flyway enabled for migrations

Key Variables by Category

🗄️ Database

# Development (H2)
SPRING_H2_DATASOURCE_URL=jdbc:h2:mem:xpeditis;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE

# Production (MySQL)
SPRING_DATASOURCE_URL=jdbc:mysql://localhost:3306/xpeditis
SPRING_DATASOURCE_USERNAME=your_username
SPRING_DATASOURCE_PASSWORD=your_password

📧 Email

# Development (Mailtrap)
SPRING_MAIL_HOST_DEV=sandbox.smtp.mailtrap.io
SPRING_MAIL_USERNAME_DEV=your_mailtrap_username
SPRING_MAIL_PASSWORD_DEV=your_mailtrap_password

# Production
SPRING_MAIL_HOST_PROD=your-smtp-host
SPRING_MAIL_USERNAME_PROD=your-email@domain.com
SPRING_MAIL_PASSWORD_PROD=your_password

🔐 Security & OAuth2

# JWT
JWT_SECRET_KEY=your-secure-secret-key
JWT_EXPIRATION=86400000

# Google OAuth2
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

📋 License Limits

APPLICATION_LICENSE_TRIAL_MAX_USERS=5
APPLICATION_LICENSE_BASIC_MAX_USERS=50
APPLICATION_LICENSE_PREMIUM_MAX_USERS=200
APPLICATION_LICENSE_ENTERPRISE_MAX_USERS=1000

Security Notes

🛡️ Important Security Practices:

1. Never commit .env files to version control
2. Generate secure JWT secret keys for production
3. Use environment-specific secrets
4. Rotate keys regularly in production

🔑 JWT Secret Key Generation:

# Generate a secure 256-bit key
openssl rand -hex 32

# Or use online generator (ensure HTTPS):
# https://generate-secret.vercel.app/32

Usage in Application

🎯 Easy Startup Scripts

Use the provided scripts for easy development and production startup:

# Development mode (loads .env automatically)
./run-dev.sh

# Production mode (validates required variables)
./run-prod.sh

# Or traditional way
./mvnw spring-boot:run

Spring Boot Configuration Loading Order:

1. System environment variables (highest priority)
2. .env file variables
3. application-{profile}.yml files
4. application.yml (lowest priority)

🔧 All YAML files now support .env variables:

• application.yml - Base configuration with .env support
• application-dev.yml - Development overrides with .env support
• application-prod.yml - Production overrides with .env support

Docker Support

For Docker deployments, mount the .env file:

docker run -d \
  --env-file .env \
  -p 8080:8080 \
  xpeditis-backend

Troubleshooting

Common Issues:

1. Missing variables: Check .env.example for required variables
2. Database connection: Verify database credentials and host
3. Email not sending: Check SMTP configuration
4. OAuth2 not working: Verify Google Console settings and redirect URIs

Debugging:

# Enable debug logging
LOGGING_LEVEL_ROOT=DEBUG

# Show SQL queries
SPRING_JPA_SHOW_SQL=true
SPRING_JPA_FORMAT_SQL=true