Initial commit: Postfix mail server with SES relay
- Containerized Postfix configuration for mailing list management - Environment-based configuration for SES credentials - Template-based config generation for flexibility - Static virtual aliases (Phase 1) - Prepared for future web interface and SQL backend (Phase 2+) Features: - Docker Compose orchestration - Secure credential management via .env - Configurable SMTP host/port - Git-ignored sensitive files - Comprehensive documentation
This commit is contained in:
97
.github/copilot-instructions.md
vendored
Normal file
97
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,97 @@
|
||||
# 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:**
|
||||
```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
|
||||
Reference in New Issue
Block a user