stemanfredi/org-stack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
org-stack/SMTP_SETUP.md
Stefano Manfredi 2866bff217 first commit
2025-12-01 14:58:40 +00:00

3.7 KiB
Raw Permalink Blame History

SMTP Email Notification Setup

Configure SMTP email notifications for password resets, 2FA codes, and user registration approvals.

Quick Setup

All steps are done on your LOCAL machine (the one with the org-stack git repo).

1. Edit Local .env File

On your local machine, edit .env and add your SMTP credentials:

# Enable SMTP
SMTP_ENABLED=true

# SMTP Server Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD='your-app-password'  # Use single quotes for passwords with special chars
SMTP_FROM=noreply@yourdomain.com
SMTP_USE_TLS=true

# Admin email for registration notifications
REGISTRATION_ADMIN_EMAIL=admin@yourdomain.com

Note: If your password contains special characters like ( ) $ " ', wrap it in single quotes.

2. Deploy from Local Machine

./deploy.sh

That's it! The deployment script:

  • Syncs your .env to the remote server
  • Automatically configures SMTP in all services
  • Restarts containers

SMTP Provider Examples

Gmail

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-16-char-app-password  # Create at https://myaccount.google.com/apppasswords
SMTP_USE_TLS=true

SendGrid

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=your-sendgrid-api-key
SMTP_USE_TLS=true

Mailgun

SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USER=postmaster@your-domain.mailgun.org
SMTP_PASSWORD=your-mailgun-smtp-password
SMTP_USE_TLS=true

Office 365

SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_USER=your-email@yourdomain.com
SMTP_PASSWORD=your-password
SMTP_USE_TLS=true

Testing

Test Authelia (Password Reset)

  1. Go to https://auth.yourdomain.com
  2. Click "Forgot password?"
  3. Enter your username
  4. Check email for reset link

Test Registration Service

  1. Submit a registration at https://register.yourdomain.com
  2. Admin receives notification email
  3. Approve the request at https://register.yourdomain.com/admin
  4. User receives credentials via email

Troubleshooting

Check Service Logs

Authelia:

ssh user@host 'cd ~/org-stack && docker compose logs authelia | grep -i smtp'

Registration:

ssh user@host 'cd ~/org-stack && docker compose logs registration | grep -i smtp'

Common Issues

Authentication Failed (535)

  • Gmail: Enable 2FA and create an App Password
  • Verify SMTP_USER and SMTP_PASSWORD are correct

Connection Refused

  • Check SMTP_HOST and SMTP_PORT are correct
  • Verify firewall allows outbound connections on port 587/465

Certificate Errors

  • Ensure SMTP_USE_TLS=true for port 587
  • Use SMTP_USE_TLS=false only for port 25 (not recommended)

Disable SMTP

To switch back to filesystem logging:

# In .env
SMTP_ENABLED=false

# Deploy
./deploy.sh

What Gets Sent

Authelia Sends:

  • 2FA setup verification codes
  • Password reset links
  • New device registration confirmations

Registration Service Sends:

  • Admin notification when user requests registration
  • User approval with auto-generated credentials
  • User rejection with reason

Security Notes

  • SMTP passwords are stored in .env (gitignored, not committed)
  • Use app passwords for Gmail/Google Workspace
  • Rotate passwords regularly by updating .env and redeploying

See Also