Email Configuration for Docker Deployments

This guide helps you configure outgoing email for Kordon when deployed as a Docker container in on-premise environments.

Prerequisites

• Kordon Docker image deployed and running
• Access to modify environment variables (via docker-compose.yml or .env file)
• SMTP server credentials (see Provider Options below)

Configuration Steps

1. Choose Your SMTP Provider

You need an SMTP server to send emails. Options:

• Your organization’s email server (Exchange, Office 365, Google Workspace)
• Third-party service (SendGrid, Mailgun, Postmark - see details below)
• Local mail relay (if your infrastructure has one)

2. Set Environment Variables

Add these variables to your Docker deployment configuration:

Option A: Using .env file

Create or update .env file in your deployment directory:

# Email Configuration
SMTP_HOST=smtp.your-provider.com
SMTP_USERNAME=your-email@company.com
SMTP_PASSWORD=your-password-or-api-key
SMTP_PORT=587
SMTP_DOMAIN=your-company.com
SMTP_FROM_EMAIL=noreply@company.com

# Application Configuration
APP_PUBLIC_DOMAIN=kordon.your-company.com

Then reference it in docker-compose.yml:

services:
  kordon-app:
    image: kordon-app:latest
    env_file:
      - .env

Option B: Using docker-compose.yml

version: '3.8'
services:
  kordon-app:
    image: kordon-app:latest
    environment:
      # Email Configuration - Required
      SMTP_HOST: smtp.your-provider.com
      SMTP_USERNAME: your-email@company.com
      SMTP_PASSWORD: your-password-or-api-key

      # Email Configuration - Optional (with defaults)
      SMTP_PORT: 587                          # Default: 587
      SMTP_AUTHENTICATION: cram_md5           # Default: plain
      SMTP_DOMAIN: your-company.com           # Default: kordon.app
      SMTP_ENABLE_STARTTLS_AUTO: true         # Default: true
      SMTP_FROM_EMAIL: noreply@company.com    # Default: kordon@{SMTP_DOMAIN}

      # Application Configuration
      APP_PUBLIC_DOMAIN: kordon.your-company.com

      # ... other environment variables ...

3. Test Email Configuration

After configuration, test email delivery:

# Access the running container
docker exec -it <container-name> bash

# Run the email test
bundle exec rake email:test_simple

# Or test the weekly notification job
bundle exec rails runner "TaskNotificationJob.perform_now"

4. Verify Email Delivery

Check the application logs for email delivery confirmation:

docker logs <container-name> | grep -i "mail\|email\|smtp"

Successful configuration shows:

[Email] SMTP configured successfully
[Email] Test email sent to user@example.com

Failed configuration shows:

[Email] SMTP_HOST not configured; email delivery disabled.

SMTP Provider Options

Using Your Organization’s Email Server

Microsoft Exchange / Office 365

SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_USERNAME=your-email@company.com
SMTP_PASSWORD=your-password
SMTP_AUTHENTICATION=login
SMTP_ENABLE_STARTTLS_AUTO=true

Note: You may need to:

• Enable SMTP authentication in Exchange admin
• Use an app-specific password if MFA is enabled
• Whitelist the Kordon server IP address

Google Workspace

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@company.com
SMTP_PASSWORD=your-app-password  # Not your regular password
SMTP_ENABLE_STARTTLS_AUTO=true

Important:

• App Passwords required - Generate at: Admin console → Security → 2-Step Verification → App passwords
• Google Workspace is deprecating username/password auth in March 2025
• Consider migrating to OAuth2 or a dedicated email service

Using Third-Party Email Services (Recommended)

SendGrid

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey  # Literal string "apikey"
SMTP_PASSWORD=SG.your-api-key-here
SMTP_DOMAIN=your-company.com

Setup Steps:

1. Sign up at sendgrid.com
2. Verify your email address
3. Create API Key: Settings → API Keys → Create API Key
4. Choose “Restricted Access” → Enable “Mail Send” permission
5. Verify your sender domain (recommended for production)

Mailgun

SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USERNAME=postmaster@your-domain.mailgun.org
SMTP_PASSWORD=your-mailgun-smtp-password
SMTP_DOMAIN=your-domain.mailgun.org

Setup Steps:

1. Sign up at mailgun.com
2. Add and verify your domain
3. Add required DNS records (SPF, DKIM, CNAME)
4. Get SMTP credentials from: Sending → Domain settings → SMTP credentials

Using a Local Mail Relay

If your organization has a local SMTP relay (like Postfix):

SMTP_HOST=mail.internal.company.com  # or 192.168.1.100
SMTP_PORT=25                          # or 587
SMTP_USERNAME=                        # Leave empty if no auth required
SMTP_PASSWORD=                        # Leave empty if no auth required
SMTP_AUTHENTICATION=                  # Leave empty for open relay

Note: Unauthenticated relays are only recommended for internal, trusted networks.

Troubleshooting

Email Not Sending

Check 1: Verify SMTP configuration is loaded

docker logs <container-name> 2>&1 | grep -i smtp

Look for:

• [Email] SMTP configured successfully (good)
• [Email] SMTP_HOST not configured; email delivery disabled (bad - check env vars)

Check 2: Test SMTP connection

docker exec -it <container-name> bash
bundle exec rake email:test_simple

Check 3: Review application logs

docker logs -f <container-name>

Look for SMTP errors like:

• Net::SMTPAuthenticationError - Wrong username/password
• Net::SMTPFatalError - Wrong SMTP settings (host/port)
• Errno::ECONNREFUSED - Can’t reach SMTP server (firewall/network issue)

Common Issues

Authentication Failures

Net::SMTPAuthenticationError: 535 Authentication failed

Solutions:

• Verify username/password are correct
• For Gmail/Google Workspace: Use app-specific password, not regular password
• For SendGrid: Username must be literal string apikey
• Check if 2FA/MFA is enabled - may need app password

Connection Refused

Errno::ECONNREFUSED: Connection refused - connect(2)

Solutions:

• Check if SMTP_HOST is reachable from Docker container
• Verify firewall allows outbound connections on SMTP_PORT (usually 587)
• Check if using correct port (587 for TLS, 465 for SSL, 25 for plain)

SSL/TLS Errors

OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0

Solutions:

• Set SMTP_ENABLE_STARTTLS_AUTO=true for port 587
• Set SMTP_ENABLE_STARTTLS_AUTO=false for port 465
• Try different port (587 vs 465)

Email Features in Kordon

Once configured, Kordon sends these automated emails:

Weekly Task Notifications

Schedule: Every Monday morning
Recipients: Users who haven’t disabled notifications
Content:

• Overdue tasks assigned to user’s groups
• Tasks due in the next 7 days
• Direct links to each task

Configuration: Users can enable/disable in their profile settings

Task Assignement Notifications

Schedule: Summary of assignments every ~10 minutes Recipients: Users who haven’t disabled notifications Content: List of new items assigned to the user.

Configuration: Users can enable/disable in their profile settings

Assignment Notification Batching

The assignment notification system uses smart batching to prevent email spam when multiple items are assigned in quick succession. Instead of sending an email for each individual assignment, the system waits for a 10-minute quiet period after the last assignment before sending a single consolidated email. How it works:

• When a user is assigned to an item (as owner, manager, or assignee), the system creates or updates a PendingNotification record and schedules an AssignmentNotificationJob to run in 1 minute.
• The job checks if 10 minutes have passed since the last assignment. If new assignments have arrived within that window, the job reschedules itself and waits another minute to check again.
• Once the 10-minute window has elapsed with no new assignments, the job verifies that all assignments still exist and are still valid (the user is still assigned), then sends a single email containing all assignments grouped by type (Controls, Risks, Assets, etc.).
• If assignments are removed or the user is unassigned before the email is sent, those items are automatically filtered out during the verification step.

This approach ensures users receive timely notifications without being overwhelmed by email volume during bulk assignment operations, while using the database as the source of truth to handle concurrent updates and job retries gracefully.