mail-services/QUICKSTART.md

# 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`**
```yaml
source:
  repoURL: https://github.com/YOUR_USERNAME/mail-services.git  # ← CHANGE THIS
```

**File: `argocd-apps/snappymail.yaml`**
```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:
```yaml
secret:
  create: true
  name: stalwart-credentials
  adminPassword: "CHANGE_ME_PLEASE_USE_STRONG_PASSWORD"  # ← CHANGE THIS!
```

Replace with a strong password:
```yaml
  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`:**
```yaml
ingress:
  hosts:
    - host: mail.YOUR-DOMAIN.com  # ← Update
```

**`manifests/snappymail/values.yaml`:**
```yaml
ingress:
  hosts:
    - host: webmail.YOUR-DOMAIN.com  # ← Update
```

## 🚀 Deployment Steps

### Step 1: Commit and Push to Git

```bash
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

```bash
# 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

```bash
# 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

```dns
; 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
```bash
# Check PVC status
kubectl describe pvc -n mail

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

### Can't access web UIs
```bash
# 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
```bash
# 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](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](MAIL_STACK_README.md) for detailed documentation.