Configuration Guide

Comprehensive guide for configuring the WiLicensor Server environment.

Environment Variables

All configuration is managed via environment variables in .env.local.

Database Configuration

POSTGRES_HOST=your-postgres-host.com
POSTGRES_PORT=5432
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=your_database_name
POSTGRES_SSL=true  # Set to 'false' for local development

Notes:

• PostgreSQL 12+ required
• SSL required for production databases
• Connection pooling configured automatically

Session Management

SESSION_SECRET=your_128_character_random_hex_string

Generate secret:

npm run secret

Requirements:

• Must be 128+ characters
• Use cryptographically secure random string
• Never share or commit to version control

Session Settings:

• Storage: PostgreSQL session_pg table
• Expiration: 30 days
• HTTP-only cookies
• Secure cookies in production

Email Configuration

WiLicensor uses Gmail SMTP for email delivery.

EMAIL_SENDER=your-gmail@gmail.com
EMAIL_PASSWORD=your_app_specific_password
EMAIL_FROM_ALIAS=License Server
EMAIL_RECIPIENT=admin@yourdomain.com

Gmail Setup:

1. Enable 2-factor authentication on your Gmail account
2. Generate App-Specific Password: https://support.google.com/accounts/answer/185833
3. Use the 16-character app password (not your regular Gmail password)

Email Functions:

• EMAIL_SENDER: Gmail account for sending emails
• EMAIL_PASSWORD: App-specific password (required)
• EMAIL_FROM_ALIAS: Display name in "From" field
• EMAIL_RECIPIENT: Admin email for notifications

Test Email:

node test.js

Stripe Configuration

USE_STRIPE_TEST_KEY=true  # Toggle test/production

# Production keys
STRIPE_SECRET_KEY=sk_live_xxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxx

# Optional: Test keys
STRIPE_SECRET_KEY_TEST=sk_test_xxxxx
STRIPE_WEBHOOK_SECRET_TEST=whsec_test_xxxxx

Setup:

1. Get keys from Stripe Dashboard
2. Get webhook secret from Webhooks
3. Configure webhook endpoint: https://yourdomain.com/webhook/stripe

Supported Events:

• customer.subscription.created - Create license keys
• customer.subscription.deleted - Deactivate license keys

Testing Webhooks Locally:

# Install Stripe CLI
stripe listen --forward-to localhost:5000/webhook/stripe

# Trigger test events
stripe trigger customer.subscription.created

Application Settings

SETTINGS=1    # Sync period in days
PORT=5000     # Server port (default: 5000)

SETTINGS:

• Controls license sync period
• Used in /api/check responses
• Default: 1 day

PORT:

• HTTP server port
• Default: 5000
• Must be available on host

Environment File Management

File Structure

License-Server/
├── .env.local           # Active configuration (gitignored)
├── .env.local.prod      # Production backup
├── .env.local.dev       # Development backup
├── .env example.local   # Template
└── .env copy 2.local    # Alternative template

Creating Configuration

# Copy template
cp ".env copy.local" .env.local

# Generate session secret
npm run secret

# Edit with your credentials
nano .env.local  # or use any text editor

Switching Environments

# Switch to development
mv .env.local .env.local.prod
mv .env.local.dev .env.local

# Switch back to production
mv .env.local .env.local.dev
mv .env.local.prod .env.local

Database Settings

Application Settings Table

The Settings table stores application-wide configuration:

{
  id: INTEGER,
  name: STRING,        // typically 'default'
  displayName: STRING,
  settings: STRING     // JSON stringified
}

Available Settings:

Auto-Add Products

{
  "autoAdd": true
}

When enabled, products are automatically created if they don't exist when referenced by webhooks or API calls.

Configure via Admin Dashboard:

1. Login to admin dashboard
2. Navigate to Settings
3. Toggle "Auto Add Products"
4. Save

Local Development Configuration

Development Database Setup

Windows (Chocolatey):

choco install postgresql15 --params '/Password:localdev' -y

Create Development Database:

PGPASSWORD=localdev psql -U postgres -c "CREATE DATABASE license_dev;"

Development .env.local:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=localdev
POSTGRES_DATABASE=license_dev
POSTGRES_SSL=false

# Email (use test account or production for notifications)
EMAIL_SENDER=your-test-gmail@gmail.com
EMAIL_PASSWORD=test_app_password
EMAIL_FROM_ALIAS=License Server Dev
EMAIL_RECIPIENT=dev@localhost

# Stripe (use test keys)
USE_STRIPE_TEST_KEY=true
STRIPE_SECRET_KEY=sk_test_xxxxx
STRIPE_WEBHOOK_SECRET=whsec_test_xxxxx

# Session
SESSION_SECRET=generated_secret_from_npm_run_secret

# Application
SETTINGS=1
PORT=5000

Production Configuration Checklist

Before deploying to production, verify:

• Strong SESSION_SECRET (128+ characters)
• PostgreSQL SSL enabled (POSTGRES_SSL=true)
• Production Stripe keys configured
• Gmail App-Specific Password used
• EMAIL_RECIPIENT set to admin email
• Database backups configured
• All secrets secured (not in version control)
• HTTPS enabled
• Webhook URLs configured in payment platforms
• Email delivery tested (node test.js)

Configuration Validation

Test Database Connection

# Using environment variables
psql -h $POSTGRES_HOST -U $POSTGRES_USER -d $POSTGRES_DATABASE

# Manual test
psql -h your-host -U your-user -d your-database

Test Email Configuration

node test.js

Expected output:

Email sent: 250 2.0.0 OK ...

Test Stripe Connection

# Install Stripe CLI
stripe listen --forward-to localhost:5000/webhook/stripe

# In another terminal
stripe trigger customer.subscription.created

Security Best Practices

Secrets Management

Never commit:

• .env.local files
• Session secrets
• Database passwords
• API keys
• Webhook secrets

Use secure storage:

• Environment variables in hosting platform
• Secret management services (AWS Secrets Manager, Azure Key Vault)
• Encrypted configuration files (with separate key management)

Password Requirements

SESSION_SECRET:

• Minimum 128 characters
• Cryptographically random
• Unique per environment

Database Passwords:

• Minimum 16 characters
• Mix of uppercase, lowercase, numbers, symbols
• Rotated regularly

Gmail App Passwords:

• Use app-specific passwords only
• One password per application
• Revoke if compromised

Troubleshooting Configuration

"Unable to connect to database"

Check:

1. Database is running: pg_isready -h your-host
2. Credentials correct in .env.local
3. SSL setting matches database requirements
4. Firewall allows connections

"Email sending failed"

Check:

1. App-specific password used (not regular password)
2. 2-factor authentication enabled on Gmail
3. Environment variables set correctly
4. Test with node test.js

"Invalid session secret"

Check:

1. SESSION_SECRET is set
2. Length is 128+ characters
3. No special characters causing parsing issues
4. Regenerate with npm run secret

Related Documentation

• ← Back to README
• API Documentation
• Deployment Guide
• Development Guide
• Troubleshooting Guide
• Technical Details

Last Updated: 2025-12-18