From c5d557ba2db2576924890a80069ef2a6984aefe6 Mon Sep 17 00:00:00 2001 From: jfcheng Date: Sun, 22 Feb 2026 20:02:40 -0500 Subject: [PATCH] config: Add SMTP_FROM_NAME to Vaultwarden configuration --- vaultwarden/SMTP_PROPOSAL.md | 76 ++++++++++++++++++++++++ vaultwarden/docker-compose.portainer.yml | 1 + vaultwarden/stack.env | 9 +-- 3 files changed, 82 insertions(+), 4 deletions(-) create mode 100644 vaultwarden/SMTP_PROPOSAL.md diff --git a/vaultwarden/SMTP_PROPOSAL.md b/vaultwarden/SMTP_PROPOSAL.md new file mode 100644 index 0000000..c0ab924 --- /dev/null +++ b/vaultwarden/SMTP_PROPOSAL.md @@ -0,0 +1,76 @@ +# 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](https://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: + +```env +# 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. diff --git a/vaultwarden/docker-compose.portainer.yml b/vaultwarden/docker-compose.portainer.yml index bf65dab..34bb49b 100644 --- a/vaultwarden/docker-compose.portainer.yml +++ b/vaultwarden/docker-compose.portainer.yml @@ -15,6 +15,7 @@ services: # Email (Optional but recommended for invitations & 2FA) - SMTP_HOST=${SMTP_HOST} - SMTP_FROM=${SMTP_FROM} + - SMTP_FROM_NAME=${SMTP_FROM_NAME} - SMTP_SECURITY=${SMTP_SECURITY:-starttls} - SMTP_PORT=${SMTP_PORT:-587} - SMTP_USERNAME=${SMTP_USERNAME} diff --git a/vaultwarden/stack.env b/vaultwarden/stack.env index 6223fd5..027b9d7 100644 --- a/vaultwarden/stack.env +++ b/vaultwarden/stack.env @@ -5,18 +5,19 @@ TZ=America/Toronto # Vaultwarden Configuration # Replace with your actual NAS IP/domain and https -DOMAIN=https://vaultwarden.yourdomain.com +DOMAIN=https://vault.chengs.uk # SECURITY: Enable signups to create your initial account, then set this to 'false' inside Portainer SIGNUPS_ALLOWED=true # Email Configuration (Optional) -SMTP_HOST=smtp.yourdomain.com +SMTP_HOST=smtp.gmail.com SMTP_FROM=vaultwarden@yourdomain.com +SMTP_FROM_NAME=Vaultwarden Admin SMTP_SECURITY=starttls SMTP_PORT=587 -SMTP_USERNAME=your_username -SMTP_PASSWORD=your_password +SMTP_USERNAME=jeffcheng.home@gmail.com +SMTP_PASSWORD=irlxlnvdpwxdhrex # Admin Panel Token (Optional) # IMPORTANT: Do not use plain text! Generate a secure hash by running this command via SSH on your NAS: