portioner/vaultwarden/SMTP_PROPOSAL.md

Vaultwarden SMTP Configuration Proposal

Objective: Configure Vaultwarden to send transactional emails (invites, 2FA, verifications) using a combination of Cloudflare (for the custom domain chengs.uk) and Gmail (as the outbound SMTP provider).

Approach Overview

Cloudflare provides Email Routing (inbound forwarding) but does not provide an outbound SMTP service. To send emails using your Gmail account while appearing to come from your custom domain (e.g., vault@chengs.uk), we must combine Cloudflare's inbound routing with Gmail's "Send mail as" alias feature and App Passwords.

Here is the proposed architecture:

1. Cloudflare: Routes incoming emails for vault@chengs.uk to your personal Gmail account.
2. Gmail: Configured with an "App Password" to allow Vaultwarden to securely authenticate. Gmail is also configured to allow sending as vault@chengs.uk.
3. Vaultwarden: Connects to smtp.gmail.com, authenticating with your base Gmail credentials, but sending emails from the custom alias.

---

Detailed Manual Steps

Phase 1: Cloudflare Setup (Email Routing)

Note: This is required if you want emails to come from @chengs.uk. If you simply want them to come from your @gmail.com address, you can skip to Phase 2.

1. Log into your Cloudflare Dashboard and select your domain (chengs.uk).
2. Go to Email -> Email Routing on the left sidebar.
3. Click Get Started and navigate to the Routes tab.
4. Create a Custom Address:
   • Custom address: vault (so the email is vault@chengs.uk)
   • Action: Send to
   • Destination address: your-personal-email@gmail.com
5. Cloudflare will send a verification email to your Gmail. Open it and verify the routing.
6. Once verified, ensure the Email Routing status shows as active. Cloudflare will automatically add the necessary MX and TXT (SPF) records to your DNS.

Phase 2: Gmail Setup (App Password & Alias)

Vaultwarden requires a secure way to authenticate with Gmail without using your primary password or requiring web-based 2FA prompts.

Step A: Generate an App Password

1. Go to your Google Account management page: myaccount.google.com.
2. Navigate to the Security tab.
3. Ensure 2-Step Verification is turned ON (this is a strict requirement for App Passwords).
4. Under 2-Step Verification, search for or find the App passwords section.
5. Provide an App name (e.g., "Vaultwarden NAS") and click Create.
6. Save the 16-character password. You will not see this again. This will be your SMTP_PASSWORD for Vaultwarden.

Step B: Add Custom Domain Alias (Optional, for @chengs.uk)

If you set up Cloudflare in Phase 1 and want Vaultwarden to send emails as vault@chengs.uk, you must authorize Gmail to send from this alias:

1. Open Gmail on the web and click the Gear Icon -> See all settings.
2. Go to the Accounts and Import tab.
3. Under "Send mail as", click Add another email address.
4. Enter the Name (e.g., "Vaultwarden Admin") and Email address (vault@chengs.uk). Check "Treat as an alias".
5. In the next SMTP step, Google will ask for SMTP details to send as this user. Use Gmail's own SMTP servers!
   • SMTP Server: smtp.gmail.com
   • Port: 587
   • Username: your-personal-email@gmail.com
   • Password: The 16-character App Password you generated in Step A.
   • Select Secured connection using TLS.
6. Google will send a verification code to vault@chengs.uk (which Cloudflare will forward to your Gmail). Enter the code to verify.

---

Phase 3: Vaultwarden Configuration (stack.env)

Once the manual steps above are complete, you will update your Vaultwarden stack.env file with the following variables so the container can connect to Gmail:

# Vaultwarden Domain (Must exactly match your Cloudflare Tunnel URL)
DOMAIN=https://vault.chengs.uk

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURITY=starttls
SMTP_USERNAME=your-personal-email@gmail.com
SMTP_PASSWORD=your-16-character-app-password

# The From address. 
# If you completed Phase 1 & 2B, use: vault@chengs.uk
# If you skipped them, use: your-personal-email@gmail.com
SMTP_FROM=vault@chengs.uk
SMTP_FROM_NAME=Vaultwarden Admin

After updating these values, you simply re-deploy the Portainer stack to apply the changes.