dvirlabs/mail-services
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mail-services/QUICKSTART.md

7.5 KiB
Raw Blame History

Quick Start Guide - Stalwart + SnappyMail Mail Stack

📋 What Was Created

A complete GitOps-ready mail stack with:

  • ✅ Stalwart Mail Server (all-in-one: SMTP, IMAP, Admin UI)
  • ✅ SnappyMail webmail client
  • ✅ Local Helm charts for both applications
  • ✅ ArgoCD Application manifests
  • ✅ Custom values files for dvirlabs.com
  • ✅ All manifests validated successfully

📁 File Structure Created

mail-services/
├── argocd-apps/
│   ├── stalwart.yaml           # ⚠️ UPDATE: Change repo URL
│   └── snappymail.yaml         # ⚠️ UPDATE: Change repo URL
│
├── charts/
│   ├── stalwart/               # Local Helm chart for Stalwart
│   │   ├── Chart.yaml
│   │   ├── values.yaml
│   │   └── templates/
│   │       ├── _helpers.tpl
│   │       ├── namespace.yaml
│   │       ├── secret.yaml
│   │       ├── statefulset.yaml
│   │       ├── service.yaml
│   │       └── ingress.yaml
│   │
│   └── snappymail/             # Local Helm chart for SnappyMail
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
│           ├── _helpers.tpl
│           ├── deployment.yaml
│           ├── pvc.yaml
│           ├── service.yaml
│           ├── ingress.yaml
│           └── configmap.yaml
│
├── manifests/
│   ├── stalwart/
│   │   └── values.yaml         # ⚠️ UPDATE: Change admin password
│   └── snappymail/
│       └── values.yaml
│
├── MAIL_STACK_README.md        # 📖 Full documentation
└── QUICKSTART.md               # 👈 This file

⚠️ REQUIRED CHANGES Before Deployment

1. Update Git Repository URL

Edit these files and replace YOUR_USERNAME with your actual Git username/organization:

File: argocd-apps/stalwart.yaml

source:
  repoURL: https://github.com/YOUR_USERNAME/mail-services.git  # ← CHANGE THIS

File: argocd-apps/snappymail.yaml

source:
  repoURL: https://github.com/YOUR_USERNAME/mail-services.git  # ← CHANGE THIS

2. Change Admin Password (CRITICAL!)

Edit manifests/stalwart/values.yaml:

Find this section:

secret:
  create: true
  name: stalwart-credentials
  adminPassword: "CHANGE_ME_PLEASE_USE_STRONG_PASSWORD"  # ← CHANGE THIS!

Replace with a strong password:

  adminPassword: "MyStr0ng!P@ssw0rd#2024"

⚠️ DO NOT commit this file with the default password!

3. (Optional) Update Domain Names

If you're not using dvirlabs.com, update these files:

manifests/stalwart/values.yaml:

ingress:
  hosts:
    - host: mail.YOUR-DOMAIN.com  # ← Update

manifests/snappymail/values.yaml:

ingress:
  hosts:
    - host: webmail.YOUR-DOMAIN.com  # ← Update

🚀 Deployment Steps

Step 1: Commit and Push to Git

cd c:\Users\dvirl\OneDrive\Desktop\gitea\mail-services

# Review changes
git status

# Add new files
git add argocd-apps/stalwart.yaml
git add argocd-apps/snappymail.yaml
git add charts/stalwart/
git add charts/snappymail/
git add manifests/stalwart/
git add manifests/snappymail/
git add MAIL_STACK_README.md
git add QUICKSTART.md

# Commit
git commit -m "Add Stalwart Mail Server + SnappyMail stack"

# Push to your Git server
git push origin main

Step 2: Deploy with ArgoCD

# Apply ArgoCD Applications
kubectl apply -f argocd-apps/stalwart.yaml
kubectl apply -f argocd-apps/snappymail.yaml

# Watch ArgoCD sync
kubectl get applications -n argocd -w

# Watch pods come up
kubectl get pods -n mail -w

Step 3: Verify Deployment

# Check all resources
kubectl get all -n mail

# Expected output:
# - statefulset.apps/stalwart (1/1)
# - deployment.apps/snappymail (1/1)
# - service/stalwart
# - service/snappymail
# - ingress.networking.k8s.io/stalwart
# - ingress.networking.k8s.io/snappymail

# Check PVCs
kubectl get pvc -n mail

# Check logs
kubectl logs -n mail stalwart-0
kubectl logs -n mail -l app.kubernetes.io/name=snappymail

🌐 Access the Services

Stalwart Admin UI

  • URL: https://mail.dvirlabs.com
  • Username: admin@dvirlabs.com
  • Password: (what you set in manifests/stalwart/values.yaml)

SnappyMail Webmail

  • URL: https://webmail.dvirlabs.com
  • First access: Admin panel at https://webmail.dvirlabs.com/?admin
  • Default admin password: 12345 (CHANGE IMMEDIATELY!)

⚙️ SnappyMail Configuration

After deployment, configure SnappyMail to connect to Stalwart:

  1. Go to https://webmail.dvirlabs.com/?admin
  2. Login with default password 12345
  3. Change admin password immediately
  4. Go to Domains → Add Domain
  5. Configure:
    • IMAP Server: stalwart.mail.svc.cluster.local
    • IMAP Port: 993
    • IMAP Secure: SSL/TLS
    • SMTP Server: stalwart.mail.svc.cluster.local
    • SMTP Port: 587
    • SMTP Secure: STARTTLS

📧 Setting Up Real Email

DNS Records Needed

; MX Record
@           IN  MX  10  mail.dvirlabs.com.

; A Record (use your public IP, NOT Cloudflare proxy)
mail        IN  A       YOUR_PUBLIC_IP

; SPF Record
@           IN  TXT     "v=spf1 mx ~all"

; DMARC Record
_dmarc      IN  TXT     "v=DMARC1; p=quarantine; rua=mailto:admin@dvirlabs.com"

Port Forwarding Required

For real email (not just webmail), you need to expose these ports directly:

Port 25   (SMTP)   - Receiving mail
Port 587  (SMTP)   - Sending mail
Port 993  (IMAPS)  - IMAP access

⚠️ Important: These ports CANNOT go through Cloudflare Tunnel!

🔍 Troubleshooting

Pods stuck in Pending

# Check PVC status
kubectl describe pvc -n mail

# Check if nfs-client storage class exists
kubectl get storageclass

Can't access web UIs

# Check ingress
kubectl describe ingress -n mail

# Check if DNS resolves to your cluster
nslookup mail.dvirlabs.com
nslookup webmail.dvirlabs.com

SnappyMail can't connect to Stalwart

# Test connectivity from SnappyMail pod
kubectl exec -it -n mail deploy/snappymail -- nc -zv stalwart.mail.svc.cluster.local 993

📖 Full Documentation

See MAIL_STACK_README.md for:

  • Complete architecture overview
  • External mail setup instructions
  • Security hardening guide
  • Backup and restore procedures
  • Advanced configuration options
  • External Secrets integration

✅ Validation Results

All manifests have been validated:

  • ✅ Stalwart Helm chart renders correctly
  • ✅ SnappyMail Helm chart renders correctly
  • ✅ ArgoCD Application manifests are valid
  • ✅ All Kubernetes resources are syntactically correct

🎯 Next Steps

  1. Update repo URL in ArgoCD manifests ← DO THIS FIRST!
  2. Change admin password in manifests/stalwart/values.yaml
  3. Commit and push to Git
  4. Apply ArgoCD applications
  5. Wait for deployment (2-3 minutes)
  6. Access Stalwart admin UI and configure mail settings
  7. Configure SnappyMail to connect to Stalwart
  8. Set up DNS records for real email
  9. Configure port forwarding for mail protocols

💡 Pro Tips

  • Start with web UIs only, add real mail later
  • Use External Secrets for production passwords
  • Enable DKIM in Stalwart for better deliverability
  • Monitor logs during first email tests
  • Test with mail-tester.com for deliverability score
  • Backup mail data regularly

Need help? Check MAIL_STACK_README.md for detailed documentation.