sasa-maillist/.github/copilot-instructions.md

Copilot Instructions: Mail List Manager (Postfix + SES + Web Interface)

Architecture Overview

This is a containerized mailing list management system built around Postfix as an SMTP relay through Amazon SES. Currently in Phase 1 with static configuration; planned expansion includes web frontend and SQL database for dynamic member management.

Current Components (Phase 1):

• docker-compose.yaml: Single-service orchestration with SES credentials
• postfix/: Complete Postfix container configuration
• Static virtual aliases system for mailing list distribution

Planned Architecture (Phase 2+):

• Web frontend for list management (view/add/remove members)
• SQL database backend for member storage
• Dynamic Postfix configuration generation
• Multi-service Docker Compose setup

Configuration Pattern

Current (Static): Environment variable substitution for secure credential management:

1. Credentials Flow: SES credentials passed via environment → sasl_passwd.template → runtime generation in entrypoint.sh
2. Config Files: Static configs (main.cf, virtual_aliases.cf) + dynamic SASL auth file
3. Postfix Maps: Hash databases generated at build time (virtual aliases) and runtime (SASL)

Future (Dynamic): Database-driven configuration:

• Member lists stored in SQL database
• Web interface for CRUD operations on members
• virtual_aliases.cf generated from database at runtime
• Postfix reload triggered by configuration changes

Key Files and Their Roles

• main.cf: Core Postfix config - relay through SES, domain settings, security
• sasl_passwd.template: Template for SES authentication (uses ${SES_USER}:${SES_PASS})
• virtual_aliases.cf: Static email forwarding rules (one mailing list currently)
• entrypoint.sh: Runtime credential processing and Postfix startup

Development Workflows

Building and Running:

docker-compose up --build    # Build and start mail server
docker-compose logs -f       # Monitor mail delivery logs

Adding Mailing Lists (Current):

1. Edit virtual_aliases.cf with new list → recipients mapping
2. Rebuild container (postmap runs at build time)
3. No restart needed for existing virtual alias changes

Future Web Interface Workflow:

1. Access web frontend at configured port
2. Use CRUD interface to manage mailing lists and members
3. Changes automatically update database and regenerate Postfix configs

Testing Mail Delivery:

# From inside container
echo "Test message" | mail -s "Subject" community@lists.sasalliance.org

# Check logs for SES relay status
docker-compose logs postfix | grep -E "(sent|bounced|deferred)"

Security Considerations

• SES credentials exposed in docker-compose.yaml (consider using Docker secrets)
• SASL password file permissions set to 600 in entrypoint
• TLS encryption enforced for SES relay (smtp_tls_security_level = encrypt)
• Only localhost and configured hostname accepted for local delivery

Configuration Conventions

• Hostname Pattern: lists.sasalliance.org for mailing lists, origin domain sasalliance.org
• Virtual Aliases: Simple format listname@lists.domain → recipient1, recipient2
• SES Region: EU West 2 (email-smtp.eu-west-2.amazonaws.com)
• Port Mapping: Standard SMTP port 25 exposed to host

Common Modifications

Adding Recipients to Existing List (Current): Edit virtual_aliases.cf, add comma-separated emails, rebuild container.

New Mailing List (Current): Add line to virtual_aliases.cf: newlist@lists.sasalliance.org recipients...

Credential Updates: Update SES_USER/SES_PASS in docker-compose.yaml, restart container.

Migration Considerations

When implementing the web frontend and database backend:

• Preserve existing community@lists.sasalliance.org list during migration
• Consider migration script to import current virtual aliases into database
• Plan for zero-downtime deployment with database-driven config generation
• Web interface should validate email addresses and handle duplicate members