Complete guide to configuring environment variables and external services for Timesheet.

Configuration

This guide covers all configuration options for Timesheet, including environment variables, external service integrations, and deployment settings.

Environment Variables

Timesheet uses environment variables for configuration. Copy .env.example to .env.local for development or .env.production for production.

Core Configuration

Database Configuration

# MongoDB connection string
MONGODB_URI=mongodb://localhost:27017/timesheet
# Production example:
# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/timesheet

# Database name (optional, extracted from URI if not provided)
DB_NAME=timesheet

Authentication Configuration

# NextAuth.js secret (generate with: openssl rand -base64 32)
NEXTAUTH_SECRET=your-very-secure-secret-key-here

# Application URL
NEXTAUTH_URL=http://localhost:3000
# Production example:
# NEXTAUTH_URL=https://timesheet.your-company.com

# JWT token expiry (default: 7 days)
JWT_EXPIRES_IN=7d

# Session cookie settings
SESSION_MAX_AGE=604800  # 7 days in seconds

External Services

Cloudinary (Image Storage)

# Cloudinary configuration for employee photos and clock-in images
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Upload presets (optional)
CLOUDINARY_UPLOAD_PRESET=timesheet-uploads
CLOUDINARY_FOLDER=timesheet

Email Configuration (SMTP)

# SMTP server settings
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false  # true for 465, false for other ports
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# Email sender details
EMAIL_FROM=noreply@your-company.com
EMAIL_FROM_NAME=Timesheet System

Face Detection (Optional)

# Enable/disable face detection features
ENABLE_FACE_DETECTION=true

# Face detection confidence threshold (0.0 to 1.0)
FACE_DETECTION_CONFIDENCE=0.65

# Minimum face size ratio (0.0 to 1.0)
FACE_MIN_SIZE_RATIO=0.18

Application Settings

Date and Time Configuration

# Date format for display (dd-MM-yyyy for Australian format)
DATE_FORMAT=dd-MM-yyyy
NEXT_PUBLIC_DATE_FORMAT=dd-MM-yyyy

# Time format (12 or 24 hour)
TIME_FORMAT=12
NEXT_PUBLIC_TIME_FORMAT=12

# Timezone (IANA timezone identifier)
TIMEZONE=Australia/Melbourne
NEXT_PUBLIC_TIMEZONE=Australia/Melbourne

# Week start day (0=Sunday, 1=Monday)
WEEK_START_DAY=1

Geofencing Configuration

# Default geofence radius in metres
DEFAULT_GEOFENCE_RADIUS=100

# Geofence mode: "soft" (warning) or "hard" (block)
DEFAULT_GEOFENCE_MODE=soft

# Enable GPS tracking
ENABLE_GPS_TRACKING=true

Security Settings

# Rate limiting
RATE_LIMIT_REQUESTS=100  # requests per window
RATE_LIMIT_WINDOW=900    # window in seconds (15 minutes)

# Password requirements
MIN_PASSWORD_LENGTH=8
REQUIRE_PASSWORD_COMPLEXITY=true

# Session security
SECURE_COOKIES=true      # set to false for development over HTTP
SAME_SITE_COOKIES=strict

Development vs Production

Development Environment

NODE_ENV=development

# Enable debug logging
DEBUG=true
LOG_LEVEL=debug

# Disable HTTPS requirements
SECURE_COOKIES=false

# Mock external services (optional)
MOCK_CLOUDINARY=true
MOCK_SMTP=true

Production Environment

NODE_ENV=production

# Disable debug features
DEBUG=false
LOG_LEVEL=info

# Enable security features
SECURE_COOKIES=true
FORCE_HTTPS=true

# Performance settings
ENABLE_COMPRESSION=true
CACHE_MAX_AGE=3600  # 1 hour

External Service Setup

Cloudinary Setup

Create Cloudinary Account
- Sign up at cloudinary.com
- Get your cloud name, API key, and API secret from the dashboard

Configure Upload Presets

// Create upload preset in Cloudinary dashboard:
// Settings → Upload → Add upload preset
{
  "name": "timesheet-uploads",
  "unsigned": false,
  "folder": "timesheet",
  "resource_type": "auto",
  "allowed_formats": ["jpg", "jpeg", "png", "webp"],
  "transformation": [
    {
      "width": 800,
      "height": 600,
      "crop": "limit",
      "quality": "auto:good"
    }
  ]
}

Environment Variables

CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=123456789012345
CLOUDINARY_API_SECRET=your-secret-key

Email (SMTP) Setup

Gmail Configuration

# Enable 2-factor authentication in Gmail
# Generate app password: Google Account → Security → App passwords

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-16-character-app-password

SendGrid Configuration

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=apikey
SMTP_PASS=your-sendgrid-api-key

AWS SES Configuration

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-ses-smtp-username
SMTP_PASS=your-ses-smtp-password

MongoDB Configuration

Connection String Format

# Local MongoDB
MONGODB_URI=mongodb://localhost:27017/timesheet

# MongoDB with authentication
MONGODB_URI=mongodb://username:password@localhost:27017/timesheet

# MongoDB Atlas
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/timesheet?retryWrites=true&w=majority

# MongoDB replica set
MONGODB_URI=mongodb://host1:27017,host2:27017,host3:27017/timesheet?replicaSet=rs0

Connection Options

# Add connection options to URI
MONGODB_URI=mongodb://localhost:27017/timesheet?maxPoolSize=10&serverSelectionTimeoutMS=5000&socketTimeoutMS=45000

Application Configuration

Feature Flags

Control which features are enabled:

# Core features
ENABLE_EMPLOYEE_PHOTOS=true
ENABLE_GEOFENCING=true
ENABLE_OFFLINE_MODE=true
ENABLE_FACE_DETECTION=true

# Advanced features
ENABLE_SHIFT_SWAPS=true
ENABLE_LEAVE_REQUESTS=true
ENABLE_ANALYTICS=true
ENABLE_AUDIT_LOGS=true

# Compliance features
ENABLE_AWARD_CALCULATIONS=true
ENABLE_PENALTY_RATES=true
ENABLE_BREAK_RULES=true
ENABLE_TOIL_TRACKING=true

UI Configuration

# Company branding
COMPANY_NAME=Your Company Name
COMPANY_LOGO_URL=/logo.png
PRIMARY_COLOR=#3b82f6
SECONDARY_COLOR=#64748b

# Dashboard settings
DEFAULT_DASHBOARD_VIEW=week
SHOW_EMPLOYEE_PHOTOS=true
ENABLE_DARK_MODE=true

Notification Settings

# Email notifications
NOTIFY_LATE_ARRIVALS=true
NOTIFY_MISSED_BREAKS=true
NOTIFY_OVERTIME_THRESHOLD=8  # hours

# System notifications
NOTIFY_FAILED_LOGINS=true
NOTIFY_SYSTEM_ERRORS=true
ADMIN_EMAIL=admin@your-company.com

Validation and Testing

Environment Validation

Timesheet validates environment variables on startup:

# Test configuration
npm run config:validate

# Check database connection
npm run db:check

# Test email configuration
npm run email:test

# Test Cloudinary connection
npm run cloudinary:test

Configuration Files

Next.js Configuration

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ['mongoose']
  },
  images: {
    domains: ['res.cloudinary.com'],
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'res.cloudinary.com',
        pathname: '/**',
      },
    ],
  },
  env: {
    CUSTOM_KEY: process.env.CUSTOM_KEY,
  },
}

module.exports = nextConfig

TypeScript Configuration

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Security Considerations

Environment Security

Never commit environment files to version control. Use .gitignore to exclude .env* files.

# .gitignore
.env
.env.local
.env.development
.env.production
.env.*.local

Production Security Checklist

Use strong, unique NEXTAUTH_SECRET
Enable HTTPS with SECURE_COOKIES=true
Set NODE_ENV=production
Use MongoDB Atlas or secured MongoDB instance
Implement rate limiting
Use environment-specific API keys
Enable audit logging
Regular security updates

Secrets Management

For production deployments, consider using:

AWS Secrets Manager
Azure Key Vault
Google Secret Manager
HashiCorp Vault
Kubernetes Secrets

Troubleshooting

Common Configuration Issues

Database Connection

# Test MongoDB connection
mongosh "mongodb://localhost:27017/timesheet"

# Check connection string format
node -e "console.log(new URL(process.env.MONGODB_URI))"

Email Configuration

# Test SMTP connection
npm run email:test -- --to=test@example.com

Environment Variables

# Check if variables are loaded
node -e "console.log(process.env.MONGODB_URI)"

# Validate required variables
npm run config:validate

Debug Mode

Enable debug logging for troubleshooting:

DEBUG=true
LOG_LEVEL=debug
VERBOSE_LOGGING=true

Next Steps

After configuration:

First Setup - Create admin user and initial data
Security Review - Implement security best practices
Performance Tuning - Optimise for your environment
Monitoring Setup - Configure logging and alerts
Backup Strategy - Set up automated backups

Configuration

On this page