Environment Configuration

This guide explains how to configure Alesqui Intelligence for deployment. The application requires several environment variables to be set in a .env file.

📋 Overview

Alesqui Intelligence can be deployed in two ways, each with its own configuration requirements:

Deployment Options

Deployment Type	Database	Best For	Configuration File
Atlas Deployment	MongoDB Atlas (Cloud)	Production, scalable applications	`atlas/.env`
Local Deployment	Self-hosted MongoDB (Docker)	Development, testing, self-hosted	`local/.env`

Both deployments use Docker and Docker Compose for orchestration. The application consists of:

Backend API - Java Spring Boot application (port 8080)
Frontend UI - React + TypeScript application (port 80)
Database - MongoDB (Atlas or local container)

🚀 Quick Start

Atlas Deployment

For cloud-based MongoDB Atlas deployment:

Navigate to the atlas directory:
```
cd atlas/
```
Copy the example environment file:
```
cp .env.example .env
```
Edit .env and configure your MongoDB Atlas connection, JWT secret, OpenAI API key, and SMTP settings
Start the services:
```
docker-compose up -d
```

Local Deployment

For self-hosted MongoDB deployment:

Navigate to the local directory:
```
cd local/
```
Copy the example environment file:
```
cp .env.example .env
```
Edit .env and configure MongoDB password, JWT secret, OpenAI API key, and SMTP settings
Start the services:
```
docker-compose up -d
```

🔐 Required Configuration

1. Security - JWT Configuration

JSON Web Tokens (JWT) are used for authentication and session management.

# Secret key for signing JWT tokens
# MUST be at least 256 bits (32 characters) for security
# Generate using: openssl rand -base64 32
JWT_SECRET=your-very-secure-jwt-secret-change-in-production

# Access token expiration in milliseconds
# Default: 900000 (15 minutes)
# Recommended for production: 900000 - 1800000 (15-30 minutes)
JWT_EXPIRATION=900000

# Refresh token expiration in milliseconds
# Default: 604800000 (7 days)
# Recommended for production: 604800000 - 2592000000 (7-30 days)
JWT_REFRESH_EXPIRATION=604800000

Security Best Practices:

✅ Generate a strong, random secret: openssl rand -base64 32
✅ Use different secrets for development, staging, and production
✅ Never commit JWT secrets to version control
✅ Rotate JWT secrets periodically in production

2. AI Configuration - OpenAI

The application uses OpenAI's GPT models for AI-powered features.

# OpenAI API Key
# Get your key from https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-proj-...

How to obtain your OpenAI API Key:

Go to OpenAI Platform
Sign in or create an account
Navigate to API Keys section
Click "Create new secret key"
Copy the key (you won't be able to see it again)
Set usage limits and restrictions as needed

3. Database Configuration

Configuration differs based on your deployment type.

Option A: MongoDB Atlas (Cloud-Managed)

For production deployments using MongoDB Atlas:

# MongoDB Atlas connection string
# Format: mongodb+srv://username:password@cluster.mongodb.net/dbname?retryWrites=true&w=majority
MONGODB_ATLAS_URI=mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/alesqui_intelligence?retryWrites=true&w=majority

# Database name (should match the database in your connection string)
MONGODB_DATABASE=alesqui_intelligence

Important Notes for Atlas:

Use mongodb+srv:// protocol (not mongodb://)
URL-encode special characters in passwords:
- @ → %40
- # → %23
- % → %25
- / → %2F
Whitelist your server IP in Atlas Network Access settings
For development, you can temporarily use 0.0.0.0/0 (not recommended for production)

Getting your Atlas connection string:

Log in to MongoDB Atlas
Click "Connect" on your cluster
Choose "Connect your application"
Select "Driver: Java" and "Version: 4.3 or later"
Copy the connection string and replace <password> with your actual password
Add your database name before the ?: .../alesqui_intelligence?retryWrites=...

Option B: Local MongoDB (Self-Hosted)

For local development or self-hosted production:

# MongoDB connection details
MONGODB_URI=mongodb://mongodb:27017/alesqui_intelligence
MONGODB_DATABASE=alesqui_intelligence
MONGODB_USER=admin
MONGODB_PASSWORD=secure_password_here
MONGODB_AUTH_DB=admin

Security Notes:

✅ Generate a strong password: openssl rand -base64 32
✅ Never use default passwords in production
✅ Restrict MongoDB port (27017) to internal network only

4. Email Configuration (SMTP)

⚠️ SMTP configuration is REQUIRED for user account activation. Without SMTP, users cannot activate their accounts or reset passwords.

Email service is required for:

User account activation
Password reset functionality
System notifications

# SMTP server configuration
SMTP_HOST=smtp.yourcompany.com
SMTP_PORT=587
SMTP_USER=user@yourcompany.com
SMTP_PASSWORD=smtp_password

# Email sender information
MAIL_FROM_EMAIL=noreply@yourcompany.com
MAIL_FROM_NAME=Alesqui Intelligence

Common SMTP Providers

SendGrid (Recommended for production):

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=SG.your-sendgrid-api-key
MAIL_FROM_EMAIL=noreply@yourcompany.com
MAIL_FROM_NAME=Alesqui Intelligence

Gmail (Development only):

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-specific-password
MAIL_FROM_EMAIL=noreply@yourcompany.com
MAIL_FROM_NAME=Alesqui Intelligence

📝 Note: For Gmail, you must use App Passwords, not your regular password.

Mailgun:

SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USER=postmaster@yourdomain.mailgun.org
SMTP_PASSWORD=your-mailgun-smtp-password
MAIL_FROM_EMAIL=noreply@yourcompany.com
MAIL_FROM_NAME=Alesqui Intelligence

Amazon SES:

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=your-ses-smtp-username
SMTP_PASSWORD=your-ses-smtp-password
MAIL_FROM_EMAIL=noreply@yourcompany.com
MAIL_FROM_NAME=Alesqui Intelligence

🎛️ Optional Configuration

Application Settings

# Company name displayed in the application
COMPANY_NAME=My Company

# Backend server port (internal Docker port)
PORT=8080

Frontend Configuration

# URL where users will access the frontend
# For production, use your actual domain with HTTPS
# Examples:
#   - Production: https://intelligence.yourcompany.com
#   - Staging: https://intelligence-staging.yourcompany.com
#   - Development: http://localhost
FRONTEND_URL=https://intelligence.yourcompany.com

# API URL for frontend to connect to backend
# For production behind reverse proxy: https://intelligence.yourcompany.com/api
# For development: http://localhost:8080
VITE_API_URL=https://intelligence.yourcompany.com/api

# Additional CORS allowed origins (comma-separated, optional)
# Example: https://app.example.com,https://test.example.com
CORS_ADDITIONAL_ORIGINS=

Audit Logging

# Number of days to retain audit logs before automatic deletion
# Default: 730 days (2 years)
# MongoDB TTL background task automatically removes expired logs every 60 seconds
# Minimum recommended: 90 days for compliance purposes
#
# Compliance recommendations:
# - SOC 2 / GDPR: 730 days (2 years)
# - HIPAA: 2190 days (6 years)
AUDIT_RETENTION_DAYS=730

Initial Admin User

On first startup, an admin account is automatically created if no users exist in the database.

# Custom admin email (optional)
# Default: admin@company.com
INITIAL_ADMIN_EMAIL=admin@mycompany.com

# Custom admin password (optional)
# If commented out, a secure password will be auto-generated
# The auto-generated password will be shown in the backend logs
INITIAL_ADMIN_PASSWORD=MySecurePassword123!

To view the auto-generated password:

docker-compose logs backend | grep InitialAdmin

Security Best Practices:

✅ Use auto-generated passwords (more secure)
✅ Change the password immediately after first login
✅ Use a strong, unique password if setting manually
❌ Don't commit passwords to version control

Corporate Proxy (Optional)

Only required if your organization uses a corporate proxy.

# Corporate proxy configuration (optional)
# PROXY_HOST=proxy.mycompany.com
# PROXY_PORT=8080

Docker Image Versions

# Specify the version tags for Docker images
# Use 'latest' for the most recent version, or specify a version like 'v1.0.0'
BACKEND_VERSION=latest
FRONTEND_VERSION=latest

📝 Complete Configuration Examples

Atlas Deployment Example

# =============================================================================
# DOCKER IMAGE VERSIONS
# =============================================================================
BACKEND_VERSION=latest
FRONTEND_VERSION=latest

# =============================================================================
# MONGODB ATLAS CONFIGURATION
# =============================================================================
MONGODB_ATLAS_URI=mongodb+srv://alesqui_admin:MyP%40ss%23123@cluster0.abc123.mongodb.net/alesqui_intelligence?retryWrites=true&w=majority
MONGODB_DATABASE=alesqui_intelligence

# =============================================================================
# SECURITY - JWT TOKENS
# =============================================================================
JWT_SECRET=P8x9mK2nQ5vW7zA3bC6eF4gH8jL1mN0pR2sT5uV8xY1zA3bC6eF9
JWT_EXPIRATION=900000
JWT_REFRESH_EXPIRATION=604800000

# =============================================================================
# AI CONFIGURATION - OpenAI
# =============================================================================
OPENAI_API_KEY=sk-proj-abc123xyz789...

# =============================================================================
# APPLICATION CONFIGURATION
# =============================================================================
COMPANY_NAME=Acme Corporation
PORT=8080
FRONTEND_URL=https://intelligence.acme.com
VITE_API_URL=https://intelligence.acme.com/api
CORS_ADDITIONAL_ORIGINS=

# =============================================================================
# EMAIL CONFIGURATION (REQUIRED)
# =============================================================================
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=SG.abc123xyz789...
MAIL_FROM_EMAIL=noreply@acme.com
MAIL_FROM_NAME=Acme Intelligence

# =============================================================================
# AUDIT LOGGING
# =============================================================================
AUDIT_RETENTION_DAYS=730

# =============================================================================
# INITIAL ADMIN USER
# =============================================================================
INITIAL_ADMIN_EMAIL=admin@acme.com
# INITIAL_ADMIN_PASSWORD=  # Leave commented for auto-generation

# =============================================================================
# PROXY (Optional)
# =============================================================================
# PROXY_HOST=proxy.acme.com
# PROXY_PORT=8080

Local Deployment Example

# =============================================================================
# DOCKER IMAGE VERSIONS
# =============================================================================
BACKEND_VERSION=latest
FRONTEND_VERSION=latest

# =============================================================================
# MONGODB CONFIGURATION (Local)
# =============================================================================
MONGODB_URI=mongodb://mongodb:27017/alesqui_intelligence
MONGODB_DATABASE=alesqui_intelligence
MONGODB_USER=admin
MONGODB_PASSWORD=uX2nM5pQ8sV1wZ4aC7eF0hJ3kL6mN9qR2tU5vX8yA1bD4eG7iK0
MONGODB_AUTH_DB=admin

# =============================================================================
# SECURITY - JWT TOKENS
# =============================================================================
JWT_SECRET=P8x9mK2nQ5vW7zA3bC6eF4gH8jL1mN0pR2sT5uV8xY1zA3bC6eF9
JWT_EXPIRATION=900000
JWT_REFRESH_EXPIRATION=604800000

# =============================================================================
# AI CONFIGURATION - OpenAI
# =============================================================================
OPENAI_API_KEY=sk-proj-abc123xyz789...

# =============================================================================
# APPLICATION CONFIGURATION
# =============================================================================
COMPANY_NAME=Acme Corporation
PORT=8080
FRONTEND_URL=http://localhost
VITE_API_URL=http://localhost:8080
CORS_ADDITIONAL_ORIGINS=

# =============================================================================
# EMAIL CONFIGURATION (REQUIRED)
# =============================================================================
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=developer@acme.com
SMTP_PASSWORD=abcd-efgh-ijkl-mnop
MAIL_FROM_EMAIL=noreply@acme.com
MAIL_FROM_NAME=Acme Intelligence

# =============================================================================
# AUDIT LOGGING
# =============================================================================
AUDIT_RETENTION_DAYS=730

# =============================================================================
# INITIAL ADMIN USER
# =============================================================================
INITIAL_ADMIN_EMAIL=admin@acme.com
# INITIAL_ADMIN_PASSWORD=  # Leave commented for auto-generation

# =============================================================================
# PROXY (Optional)
# =============================================================================
# PROXY_HOST=proxy.acme.com
# PROXY_PORT=8080

🔒 Production Security Checklist

Before deploying to production, ensure you have:

🔍 Troubleshooting

Common Issues

Connection to MongoDB failed

For MongoDB Atlas:

Verify MONGODB_ATLAS_URI is correct and properly formatted
Ensure your server IP is whitelisted in Atlas Network Access
Check password is URL-encoded (special characters)
Verify connection string uses mongodb+srv:// (not mongodb://)
Test connection: docker-compose config | grep MONGODB_ATLAS_URI

For Local MongoDB:

Verify MONGODB_URI is correct
Ensure MongoDB container is running: docker-compose ps mongodb
Check MongoDB password matches in .env

Test connection:

docker exec alesqui-mongodb mongosh \
  --username admin \
  --password YOUR_PASSWORD \
  --authenticationDatabase admin \
  --eval "db.adminCommand('ping')"

OpenAI API errors

Verify OPENAI_API_KEY is valid and starts with sk-proj-
Check API key has sufficient credits at OpenAI Platform
Ensure no rate limiting issues
Check backend logs: docker-compose logs backend | grep -i openai

Email sending fails (CRITICAL - users cannot activate accounts)

Verify SMTP credentials are correct
Check SMTP port and host configuration
Ensure firewall allows outbound SMTP connections (port 587 or 465)
For Gmail: Use App Password instead of regular password
Test SMTP connectivity: telnet smtp.gmail.com 587
Check backend logs: docker-compose logs backend | grep -i smtp

CORS errors

Verify FRONTEND_URL matches your frontend's actual URL
Include protocol (http:// or https://)
Check for trailing slashes (avoid them)
Verify browser console for specific CORS error messages
For multiple origins, use CORS_ADDITIONAL_ORIGINS

Backend won't start

Check configuration syntax: cat .env | grep -v "^#" | grep -v "^$"
Verify no spaces around = in .env file
Check Docker logs: docker-compose logs backend
Verify all required variables are set
Ensure ports 80 and 8080 are available

JWT Authentication Errors

Verify JWT_SECRET is at least 32 characters: grep JWT_SECRET .env | awk -F= '{print length($2)}'
Ensure JWT_SECRET doesn't contain special characters that need escaping
Check JWT_EXPIRATION is a valid number in milliseconds

Installation Guide - Complete installation instructions
Architecture Documentation - System architecture overview
Enterprise Readiness - Security and compliance guide
Distribution Repository - Docker deployment guides

For more detailed deployment guides:

Atlas Deployment - MongoDB Atlas setup
Local Deployment - Self-hosted MongoDB setup
Troubleshooting - Common issues and solutions

📞 Support

If you encounter configuration issues:

GitHub Issues: Report an issue
Email: support@alesqui.com
Documentation: Full guides available in the distribution repository

Documentation