97 lines
4.0 KiB
Markdown
97 lines
4.0 KiB
Markdown
# 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, with members able to join multiple lists
|
|
- 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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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 |