|
| 1 | +# MailAD Codebase Guide for AI Agents |
| 2 | + |
| 3 | +## Project Overview |
| 4 | +MailAD is a bash-based mail server provisioning tool that links to Active Directory (Samba/Windows) for user management. It automates multi-service mail infrastructure deployment on Debian/Ubuntu systems. The project targets Cuba's specific regulatory requirements but is usable anywhere. |
| 5 | + |
| 6 | +**Key services provisioned:** Postfix (SMTP), Dovecot (IMAP/POP3), Amavis (AV filtering), SpamAssassin, optional Roundcube/SnappyMail webmail, Nginx frontend. |
| 7 | + |
| 8 | +## Architecture Pattern: Template-Based Provisioning |
| 9 | + |
| 10 | +The core workflow uses **template files + variable substitution**: |
| 11 | +1. **Template files** in `var/` directories (e.g., `var/postfix/main.cf`, `var/dovecot-2.2/dovecot.conf`) contain placeholders like `_DOMAIN_`, `_ADMINMAIL_`, `_MESSAGESIZE_` |
| 12 | +2. **Configuration** comes from two sources: |
| 13 | + - `common.conf`: system-wide defaults (OS support matrix, package lists, service names, version detection) |
| 14 | + - `mailad.conf`: user-facing deployment config (domain, hostname, LDAP credentials, feature toggles) |
| 15 | +3. **Provisioning** (see [scripts/provision.sh](scripts/provision.sh#L85-L96)): `sed` replaces placeholders with values, then copies templated configs to `/etc/` |
| 16 | +4. **Version handling**: Dovecot configs differ by version (2.2/2.3/2.4 in `var/dovecot-*/`)—detection happens in provision.sh |
| 17 | + |
| 18 | +## Critical Developer Workflows |
| 19 | + |
| 20 | +### Building/Deploying |
| 21 | +```bash |
| 22 | +make conf # Interactive config setup |
| 23 | +make deps # Install build dependencies |
| 24 | +make conf-check # Validate AD connectivity + config |
| 25 | +make install # Install packages (no configuration) |
| 26 | +make provision # Apply configurations to /etc/ + start services |
| 27 | +make all # Full sequence: deps → conf-check → install → provision |
| 28 | +``` |
| 29 | + |
| 30 | +### Testing |
| 31 | +- **Manual tests:** [tests/test.sh](tests/test.sh) runs SMTP/auth validation against a live server |
| 32 | +- **Test dependencies:** `.mailadmin.auth` file required (credentials for admin + national/local test users) |
| 33 | +- **Key test scenarios:** receive emails, auth for users, reject open relay, size limits, restriction levels |
| 34 | + |
| 35 | +### Configuration Upgrade Pattern |
| 36 | +- `scripts/confupgrade.sh` runs before provision to detect and apply config migrations |
| 37 | +- Backward compatibility is maintained by detecting old config keys and transforming them |
| 38 | + |
| 39 | +## Project Conventions & Patterns |
| 40 | + |
| 41 | +### Variable Naming in Configs |
| 42 | +- **User-facing** (in `mailad.conf`): `DOMAIN`, `HOSTNAME`, `ADMINMAIL`, `MESSAGESIZE`, feature flags like `DOVECOT_SPAM_FILTER_ENABLED` |
| 43 | +- **System** (in `common.conf`): `SERVICENAMES` (array of systemd services), `OS_SUPPORTED`/`OS_LEGACY`/`OS_DISCONTINUED` (OS matrices), `VARS` (dynamically extracted from `mailad.conf`) |
| 44 | +- **Escaped versions**: `ESCDOMAIN`, `ESCNATIONAL` for sed patterns (backslash escaping dots/special chars) |
| 45 | + |
| 46 | +### Postfix Rules & LDAP Integration |
| 47 | +- **LDAP bind:** Configured in [var/postfix/ldap/](var/postfix/ldap/) with separate files for lookup tables (domains, users, groups) |
| 48 | +- **Mail restrictions:** Domain-local vs. national/international users controlled via `ESCNATIONAL` regex in `filter_loc` and `filter_nat` files |
| 49 | +- **Alias management:** [scripts/groups.sh](scripts/groups.sh) runs daily (cron) to sync AD groups as email aliases |
| 50 | + |
| 51 | +### Dovecot LDAP & Sieve |
| 52 | +- **LDAP auth:** Dovecot config points to AD via [var/dovecot-*/dovecot-ldap.conf.ext](var/dovecot-2.2/dovecot-ldap.conf.ext) |
| 53 | +- **Mailbox quotas:** Per-user sizes from AD `wWWHomePage` field, defaults to `DEFAULT_MAILBOX_SIZE` |
| 54 | +- **Sieve filtering:** Auto-creates spam filter if `DOVECOT_SPAM_FILTER_ENABLED` is set |
| 55 | + |
| 56 | +### Amavis/AV Integration |
| 57 | +- **Config location:** [var/amavis/conf.d/](var/amavis/conf.d/) with modular structure (e.g., `50-user` for customization) |
| 58 | +- **Feature toggles:** `ANTIVIRUS`, `SPAMD_PROXY` enable ClamAV and SpamAssassin via sed substitution (comment/uncomment pattern) |
| 59 | +- **Spam bypass:** [scripts/provision.sh](scripts/provision.sh#L350-L394) conditionally enables `@bypass_spam_checks_maps` |
| 60 | + |
| 61 | +### Backup/Restore |
| 62 | +- [scripts/backup.sh](scripts/backup.sh), [scripts/restore.sh](scripts/restore.sh), [scripts/custom_restore.sh](scripts/custom_restore.sh) preserve `/etc/` configurations |
| 63 | +- No user mailbox data included—focus is config portability |
| 64 | + |
| 65 | +## Git & Issue Workflow |
| 66 | +- **Branch naming:** `{username}_t{issue#}_{short_description}` (e.g., `stdevPavelmc_t228_fix_cron`) |
| 67 | +- **Commits:** Start with `Refs #{issue#}` to auto-link to GitHub issues |
| 68 | +- **Pull requests:** Mention @stdevPavelmc when ready to merge; CI/CD (GitHub Actions) validates against test suite |
| 69 | + |
| 70 | +## Key Integration Points |
| 71 | +- **Active Directory:** All user management via LDAP bind DN (configurable, typically Domain Admin) |
| 72 | +- **DNS:** Checked by [scripts/check_dns_records.sh](scripts/check_dns_records.sh) for MX/SPF/DKIM readiness |
| 73 | +- **Mail storage:** `/home/vmail/` (uid:gid 5000:5000)—can be NFS mount |
| 74 | +- **Webmail:** Roundcube or SnappyMail with SQLite/MySQL backend, installed via [scripts/webmails.sh](scripts/webmails.sh) |
| 75 | + |
| 76 | +## When Adding Features |
| 77 | +1. Add toggle in `mailad.conf` (e.g., `NEW_FEATURE_ENABLED`) |
| 78 | +2. Add corresponding template files or sed edits in `scripts/provision.sh` |
| 79 | +3. Version-gate if affecting Postfix/Dovecot (query `common.conf` OS/version arrays) |
| 80 | +4. Update [tests/test.sh](tests/test.sh) to validate new feature |
| 81 | +5. Document in [README.md](README.md) and [Features.md](Features.md) |
0 commit comments