auctiora/docs/EMAIL_CONFIGURATION.md

Email Notification Configuration Guide

Overview

The application uses Gmail SMTP to send email notifications for auction alerts and lot updates.

Gmail App Password Setup (Required for michael@appmodel.nl)

Why App Passwords?

Google requires App Passwords instead of your regular Gmail password when using SMTP with 2-factor authentication enabled.

Steps to Generate Gmail App Password:

1. Enable 2-Factor Authentication (if not already enabled)

   • Go to https://myaccount.google.com/security
   • Under "Signing in to Google", enable "2-Step Verification"

2. Generate App Password

   • Go to https://myaccount.google.com/apppasswords
   • Or navigate: Google Account → Security → 2-Step Verification → App passwords
   • Select app: "Mail"
   • Select device: "Other (Custom name)" → Enter "Auctiora Monitor"
   • Click "Generate"
   • Google will display a 16-character password (e.g., abcd efgh ijkl mnop)
   • Copy this password immediately (you won't see it again)

3. Use the App Password

   • Use this 16-character password (without spaces) in your configuration
   • Format: abcdefghijklmnop

Configuration

Method 1: Environment Variable (Recommended for Production)

Set the auction.notification.config property in your application.properties or via environment variable:

# Format: smtp:username:password:recipient_email
auction.notification.config=smtp:michael@appmodel.nl:YOUR_APP_PASSWORD:michael@appmodel.nl

Example with Docker:

docker run -e AUCTION_NOTIFICATION_CONFIG="smtp:michael@appmodel.nl:abcdefghijklmnop:michael@appmodel.nl" ...

Method 2: application.properties (Development)

Edit src/main/resources/application.properties:

# BEFORE (desktop only):
auction.notification.config=desktop

# AFTER (desktop + email):
auction.notification.config=smtp:michael@appmodel.nl:YOUR_APP_PASSWORD_HERE:michael@appmodel.nl

Format Breakdown

The configuration string format is:

smtp:<SMTP_USERNAME>:<APP_PASSWORD>:<RECIPIENT_EMAIL>

Where:

• SMTP_USERNAME: Your Gmail address (michael@appmodel.nl)
• APP_PASSWORD: The 16-character app password from Google (no spaces)
• RECIPIENT_EMAIL: Email address to receive notifications (can be same as sender)

Configuration Examples

Desktop Notifications Only

auction.notification.config=desktop

Email Notifications Only

auction.notification.config=smtp:michael@appmodel.nl:abcdefghijklmnop:michael@appmodel.nl

Both Desktop and Email (Recommended)

The SMTP configuration automatically enables both:

auction.notification.config=smtp:michael@appmodel.nl:abcdefghijklmnop:michael@appmodel.nl

Send to Multiple Recipients

To send to multiple recipients, you can modify the code or set up Gmail forwarding rules.

SMTP Configuration Details

The application uses these Gmail SMTP settings (hardcoded):

• Host: smtp.gmail.com
• Port: 587
• Security: STARTTLS
• Authentication: Required

Testing Configuration

After configuration, restart the application and check logs:

Success:

✓ OpenCV loaded successfully
Email notification: Test Alert

Failure (wrong password):

WARN NotificationService - Email failed: 535-5.7.8 Username and Password not accepted

Troubleshooting

Error: "Username and Password not accepted"

• Cause: Invalid App Password or 2FA not enabled
• Solution:
  1. Verify 2-Factor Authentication is enabled
  2. Generate a new App Password
  3. Ensure no spaces in the password
  4. Check for typos in email address

Error: "AuthenticationFailedException"

• Cause: Incorrect credentials format
• Solution: Verify the format: smtp:user:pass:recipient

Gmail Blocks Sign-in

• Cause: "Less secure app access" is disabled (deprecated by Google)
• Solution: Use App Passwords (as described above)

Configuration Not Taking Effect

• Cause: Application not restarted or environment variable not set
• Solution:
  1. Restart the application/container
  2. Verify with: docker logs auctiora | grep notification

SMTP Connection Timeout

• Error: Couldn't connect to host, port: smtp.gmail.com, 587; timeout -1
• Causes:
  1. Firewall/Network blocking port 587
  2. Corporate network blocking SMTP
  3. Antivirus/security software blocking connections
  4. No internet access in test/container environment
• Solutions:
  1. Test connectivity:

     # On Linux/Mac
     telnet smtp.gmail.com 587
     # On Windows
     Test-NetConnection -ComputerName smtp.gmail.com -Port 587
     

  2. Check firewall rules: Allow outbound connections to port 587
  3. Docker network: Ensure container has internet access

     docker exec auctiora ping -c 3 smtp.gmail.com
     

  4. Try alternative port 465 (SSL/TLS):
     • Requires code change to use mail.smtp.socketFactory
  5. Corporate networks: May require VPN or proxy configuration
  6. Windows Firewall: Add Java/application to allowed programs

Connection Succeeds but Authentication Fails

• Error: Email authentication failed - check Gmail App Password
• Solution: Verify App Password is correct and has no spaces

Security Best Practices

1. Never commit passwords to git

   • Use environment variables in production
   • Add application-local.properties to .gitignore

2. Rotate App Passwords periodically

   • Generate new App Password every 90 days
   • Revoke old passwords at https://myaccount.google.com/apppasswords

3. Use separate App Passwords per application

   • Creates "Auctiora Monitor" specific password
   • Easy to revoke if compromised

4. Monitor Gmail Activity

   • Check https://myaccount.google.com/notifications
   • Review "Recent security activity"

Example Docker Compose Configuration

services:
  auctiora:
    image: auctiora:latest
    environment:
      - AUCTION_NOTIFICATION_CONFIG=smtp:michael@appmodel.nl:${GMAIL_APP_PASSWORD}:michael@appmodel.nl
      - AUCTION_DATABASE_PATH=/mnt/okcomputer/output/cache.db
    volumes:
      - shared-auction-data:/mnt/okcomputer/output

Then set the password in .env file (not committed):

GMAIL_APP_PASSWORD=abcdefghijklmnop

Notification Types

The application sends these email notifications:

1. Lot Closing Soon (Priority: High)

   • Sent when a lot closes within 5 minutes
   • Subject: [Troostwijk] Lot nearing closure

2. Bid Updated (Priority: Normal)

   • Sent when current bid increases
   • Subject: [Troostwijk] Bid update

3. Critical Alerts (Priority: High)

   • System errors or important events
   • Subject: [Troostwijk] Critical Alert

Alternative: Desktop Notifications Only

If you don't want email notifications, use:

auction.notification.config=desktop

This will only show system tray notifications (Linux/Windows/Mac).