|
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) |
| 1 | +See AGENTS.md file for instructions |
0 commit comments