63 lines
3.9 KiB
Markdown
63 lines
3.9 KiB
Markdown
# Mail Stack on Coolify with OIDC Webmail
|
||
|
||
This stack pairs **docker-mailserver** with **SnappyMail** as a modern webmail UI that can sit behind your OIDC provider. Deploy it through Coolify with this repository.
|
||
|
||
## Components
|
||
- docker-mailserver: SMTP/IMAP server with spam/AV/Fail2Ban enabled.
|
||
- SnappyMail: lightweight webmail with OAuth2/OIDC login support.
|
||
|
||
## Prerequisites
|
||
- DNS: `MX` record to `mail.your-domain.tld`, plus `A`/`AAAA` for both `mail.your-domain.tld` and `webmail.your-domain.tld`.
|
||
- TLS: issue certificates (Coolify can request via Traefik/Let’s Encrypt if you publish through it).
|
||
- SMTP ports 25/465/587 and IMAP 993 open to the internet.
|
||
- An OIDC provider (e.g., Authentik, Keycloak, Azure AD) with a client ready to configure.
|
||
|
||
## Deploy with Coolify
|
||
1. **Create an application from this repo** in Coolify and choose “Docker Compose”.
|
||
2. **Volumes**: Coolify will create them from the compose file paths. Ensure the persistent paths below map to durable storage:
|
||
- `./docker-data/dms/mail-data/`, `./docker-data/dms/mail-state/`, `./docker-data/dms/mail-logs/`, `./docker-data/dms/config/`
|
||
- `./docker-data/snappymail/`
|
||
3. **Environment**: adjust `hostname` for the mailserver and expose any extra docker-mailserver envs you need (aliases, relays, etc.).
|
||
4. **Networking**: publish ports 25/465/587/993 for mail delivery. Expose port 8080 from the `webmail` service to the internet (ideally behind HTTPS via Coolify/Traefik). If you front it with Traefik, set the appropriate labels and disable the direct `ports` stanza.
|
||
5. **Deploy** the stack. Coolify will start `mailserver` and `webmail` containers.
|
||
|
||
## Bootstrap docker-mailserver
|
||
Run these once after the containers are healthy (from the host or via Coolify shell):
|
||
|
||
```bash
|
||
docker compose exec mailserver setup email add user@your-domain.tld "SuperSecretPassword"
|
||
docker compose exec mailserver setup alias add postmaster@your-domain.tld user@your-domain.tld
|
||
```
|
||
|
||
Add DNS TXT records for SPF/DKIM/DMARC using docker-mailserver guidance, then reload:
|
||
|
||
```bash
|
||
docker compose exec mailserver setup reload
|
||
```
|
||
|
||
## Configure SnappyMail for IMAP/SMTP
|
||
1. Open the admin panel at `https://webmail.your-domain.tld/?admin` (default admin password is shown on first run; change it immediately).
|
||
2. Set **IMAP** host to `mailserver`, port `993`, security **SSL/TLS**.
|
||
3. Set **SMTP** host to `mailserver`, port `587`, security **STARTTLS**, authentication **Use user credentials**.
|
||
4. Save and test with one of the mail accounts you created above.
|
||
|
||
## Enable OIDC in SnappyMail
|
||
SnappyMail supports OAuth2/OIDC providers. Configure it in the admin UI:
|
||
1. In **Admin → Domains/Auth → OAuth**, add a **Custom / Generic OIDC** provider.
|
||
2. When prompted, SnappyMail shows a **Redirect URI**; copy this exact value into your OIDC client configuration.
|
||
3. In your OIDC provider, create a public/confidential client with these basics:
|
||
- **Grant type**: Authorization Code with PKCE (preferred) or standard code.
|
||
- **Scopes**: `openid email profile`.
|
||
- **Redirect URI**: the one SnappyMail displayed.
|
||
4. Back in SnappyMail, fill the provider fields:
|
||
- **Authorization endpoint** and **Token endpoint** from your IdP.
|
||
- **UserInfo endpoint** (for email/subject mapping).
|
||
- **Client ID/Secret** matching the client you created.
|
||
- **Login attribute mapping**: map email/subject to the mailbox name (e.g., `email` → `user@your-domain.tld`).
|
||
5. Save and test “Login with <provider>”. Successful OIDC login should drop you into the mailbox without prompting for a separate password.
|
||
|
||
## Operating tips
|
||
- Back up `./docker-data/` regularly; it holds mail, state, and SnappyMail config.
|
||
- Use Coolify health checks to surface container issues; restart policies are already defined in the compose file.
|
||
- For HTTPS, prefer running `webmail` behind Coolify’s Traefik with automatic certificates instead of exposing port 8080 directly.
|
||
- If you rotate OIDC credentials, update them in SnappyMail admin immediately to avoid login failures.
|