knet-mailserver/readme.md

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):

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:

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 ”. 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.