Email - Doc update - English only

dockflare/app/templates/docs/en/Email-Docker-Deployment.md

@@ -0,0 +1,87 @@
+# Docker Deployment (Email Profile)
+
+The DockFlare Email Suite consists of two additional microservices: the **Mail Manager** and the **Webmail PWA**. These services are optional and are managed using Docker Compose **profiles**.
+
+## Enabling the Email Profile
+
+To start DockFlare with email support, you must include the `email` profile when running your Docker Compose commands.
+
+### Starting the containers
+```bash
+docker compose --profile email up -d
+```
+
+### Stopping the containers
+If you run `docker compose down`, it will stop all services including email. To restart with email again, remember to include the profile:
+```bash
+docker compose --profile email up -d
+```
+
+## Docker Compose Configuration
+
+The email services are already included in the default `docker-compose.yml`. The relevant sections are:
+
+```yaml
+  dockflare-mail-manager:
+    image: alplat/dockflare-mail-manager:stable
+    container_name: dockflare-mail-manager
+    restart: unless-stopped
+    profiles: ["email"]
+    environment:
+      - DOCKFLARE_MASTER_URL=http://dockflare:5000
+      - MAIL_DATA_PATH=/data
+    volumes:
+      - mail_data:/data
+    depends_on:
+      dockflare:
+        condition: service_started
+    networks:
+      - cloudflare-net
+      - dockflare-internal
+
+  dockflare-webmail:
+    image: alplat/dockflare-webmail:stable
+    container_name: dockflare-webmail
+    restart: unless-stopped
+    profiles: ["email"]
+    environment:
+      - DOCKFLARE_MASTER_URL=https://dockflare.TLD  # replace with your domain
+    labels:
+      - dockflare.enable=true
+      - dockflare.hostname=mail.dockflare.TLD  # replace with your domain
+      - dockflare.service=http://dockflare-webmail:80
+    depends_on:
+      dockflare-mail-manager:
+        condition: service_started
+    networks:
+      - cloudflare-net
+      - dockflare-internal
+
+volumes:
+  mail_data:
+```
+
+> **Important:** Before starting the email profile, update the two placeholder values in the `dockflare-webmail` service:
+> - `DOCKFLARE_MASTER_URL` — the public HTTPS URL of your DockFlare Master (e.g. `https://dockflare.example.com`)
+> - `dockflare.hostname` label — the subdomain where Webmail will be accessible (e.g. `mail.example.com`)
+
+## Service Breakdown
+
+| Service | Description | Port |
+| :--- | :--- | :--- |
+| `dockflare-mail-manager` | The backend engine that processes MIME, manages SQLite, and handles webhooks. | Internal only |
+| `dockflare-webmail` | The Vue-based frontend application for users. | 80 (Internal) |
+
+## Persistent Volumes
+
+The Email Suite introduces a new volume: `mail_data`.
+
+*   **Location:** `/data` inside the `mail-manager` container.
+*   **Contents:** 
+    *   `/data/db/mail.db`: The SQLite database containing all message metadata and search indices.
+    *   `/data/attachments/`: The filesystem storage for all email attachments.
+*   **Importance:** **Never delete this volume** unless you want to permanently erase all stored emails. Ensure this volume is included in your host-level backup strategy.
+
+## Verification
+
+Once the containers are started, check their status in the DockFlare Master UI under the **Email** navigation item. You should see a green "Running" status for both services in the **Container Status** card.

dockflare/app/templates/docs/en/Email-Domain-Setup.md

@@ -0,0 +1,37 @@
+# Domain Setup & Configuration
+
+Once your Docker containers are running with the `email` profile, you can begin the automated setup process in the DockFlare Web UI.
+
+## The Email Setup Wizard
+
+1.  Navigate to the **Email** page in the left-hand sidebar.
+2.  Click **Set Up Email Domain**.
+3.  Select the **Cloudflare Zone** (domain) you wish to configure.
+4.  Click **Confirm Setup**.
+
+### What happens during setup?
+DockFlare performs several automated steps via the Cloudflare API:
+*   **Enables Email Routing** on your zone.
+*   **Configures DNS:** Creates MX records, SPF (TXT), DMARC (TXT), and DKIM (CNAME) records as required by Cloudflare Email Routing.
+*   **Provisions Storage:** Creates a dedicated R2 bucket for temporary transit buffering.
+*   **Deploys Workers:** Deploys an Inbound Worker (to receive mail) and an Outbound Worker (to send mail).
+*   **Initializes KV:** Creates a Cloudflare KV namespace to track mailbox quotas at the edge.
+
+## Verifying DNS Health
+
+DNS changes can take time to propagate. On the Email page, you will see a **DNS Records** card.
+*   Click **Verify DNS** to check the current status of your MX, SPF, and DMARC records. (DKIM is managed automatically by Cloudflare Email Routing and is not separately verified here.)
+*   The system will show green badges when the records are correctly detected in the public DNS.
+
+## Updating / Redeploying Workers
+
+If you update your DockFlare version or change your API permissions, you may need to refresh your workers.
+*   Click the **Redeploy Workers** button.
+*   This will re-upload the latest worker logic and re-sync all bindings (R2, KV, Webhook Secrets) without affecting your stored email data.
+
+## Tearing Down a Domain
+
+If you wish to stop hosting email for a domain:
+*   Click **Teardown Domain**.
+*   This will remove routing rules, Inbound/Outbound Workers, the R2 transit bucket, and DNS records from Cloudflare.
+*   **Note:** This does *not* delete your local email data in the `mail_data` volume. Enable **Include local data** in the teardown dialog if you also want to wipe messages and attachments stored on your server.

dockflare/app/templates/docs/en/Email-Mailbox-Management.md

@@ -0,0 +1,41 @@
+# Mailbox & Quota Management
+
+The **Mailbox Management** card on the Email page is where you control who can receive mail and how much storage they are allowed to use.
+
+## Creating Mailboxes
+
+1.  Click **Add Mailbox**.
+2.  **Address:** Enter the desired prefix (e.g., `info`). The domain is automatically appended.
+3.  **Display Name:** The name shown to recipients (e.g., `Support Team`).
+4.  **Quota:** Select the initial storage limit.
+
+## Understanding the Quota System
+
+DockFlare uses a tiered quota system to ensure your server doesn't run out of disk space while providing a graceful experience for users.
+
+### Soft Limit (Quota)
+When a mailbox exceeds its configured quota:
+*   The system inserts a **Warning Email** from a system address into the user's Inbox.
+*   The user can still receive mail until they hit the Hard Limit.
+*   The quota bar in the Master UI will turn **Yellow**.
+
+### Hard Limit (Rejection)
+The Hard Limit is automatically calculated as **Soft Limit + 15% (minimum 10MB grace buffer)**.
+*   **Edge Rejection:** Rejection happens at the Cloudflare Edge. The sender's mail server receives an SMTP error **5.2.2 Mailbox full**.
+*   The email never enters your R2 transit bucket or your local server, saving bandwidth.
+*   The quota bar in the Master UI will turn **Red**.
+
+## Catch-all Mailboxes
+
+A Catch-all mailbox receives all emails sent to your domain that do not match an existing, specific mailbox.
+1.  Click **Configure Catch-all**.
+2.  Select a destination mailbox.
+3.  Click **Enable**.
+
+## Auto-Responders (Vacation Mode)
+
+You can set up automated replies for any mailbox:
+1.  Click the **Auto-Responder** icon (robot) next to a mailbox.
+2.  Enter your message and subject.
+3.  Set a **Date Range** for when the responder should be active.
+4.  **Reply Interval:** Set how often the responder should reply to the same sender (e.g., once every 24 hours) to prevent "email loops."

dockflare/app/templates/docs/en/Email-Maintenance.md

@@ -0,0 +1,44 @@
+# Maintenance & Troubleshooting
+
+DockFlare Email is designed to be low-maintenance, but understanding how to handle backups and common issues is important for long-term reliability.
+
+## Backup & Restore
+
+All your email data is stored in the `mail_data` Docker volume. To perform a backup:
+
+1.  **Full Volume Backup:** Back up the entire volume folder on your host machine. This is the safest option as it captures the raw SQLite database and all attachment files.
+2.  **UI Backup:** On the **Email** page, find the **Backup & Restore** card and click **Download Backup**. This generates a ZIP archive of your email data. Note: this backup contains emails and attachments in plain text — store it securely.
+
+To restore:
+1.  Ensure the `mail_data` volume is mounted in your `docker-compose.yml`.
+2.  On the **Email** page in the **Backup & Restore** card, select your ZIP file and click **Restore Backup**. This will permanently overwrite existing email data.
+
+## Logs
+
+Debugging delivery issues often requires looking at the logs of the `dockflare-mail-manager` container.
+
+```bash
+docker logs -f dockflare-mail-manager
+```
+
+The Email page also includes a **Delivery Logs** card. Click **Investigate** to open the log viewer, which has two tabs:
+*   **Outbound Log:** History of all outbound email attempts.
+*   **Bounce Log:** History of all delivery failures (NDRs) for emails you sent.
+
+## Resilience & Self-Healing
+
+### R2 Buffering
+If your server goes offline (e.g., power outage, internet downtime), the Cloudflare Inbound Worker will notice that your local webhook is unreachable. It will keep the email safely in the **R2 temp_cache**.
+*   The worker runs a **Cron Job** every 5 minutes.
+*   It will automatically retry delivery of any buffered emails until your server is back online.
+
+### Filesystem Parity
+The Mail Manager includes a startup routine that ensures the database and the filesystem are in sync. If an attachment file exists but has no database record (an "orphan"), it will be automatically purged to save space.
+
+## Common Issues
+
+### "Worker Error" in Logs
+Ensure your API Token has the `Workers Scripts` and `Workers KV Storage` permissions. If you recently updated DockFlare, you may need to click **Redeploy Workers** on the Email page to sync new environment variables.
+
+### Mail is delayed
+Check the **Cron** logs in the Cloudflare Worker dashboard. If your local server is under heavy load or having network issues, the worker will buffer mail to R2 and deliver it once your server responds.

dockflare/app/templates/docs/en/Email-Overview.md

@@ -0,0 +1,30 @@
+# Email Suite Overview
+
+DockFlare Email is a fully self-hosted, sovereign email system built on top of your existing DockFlare infrastructure. It is designed to provide the convenience of cloud-based email with the privacy and control of self-hosting.
+
+## The Sovereign Email Concept
+
+Traditionally, self-hosting email is difficult due to "home IP blacklisting," where residential IP addresses are blocked by major email providers. DockFlare solves this by using Cloudflare as a **stateless delivery network**:
+
+1.  **Cloudflare** handles the heavy lifting of SMTP delivery, MX routing, and temporary buffering.
+2.  **DockFlare** owns the data. Your messages, attachments, and mailbox configurations are stored on your own hardware.
+
+No email content persists on Cloudflare's infrastructure. It is briefly buffered in an R2 bucket during transit and is purged immediately after your local Mail Manager processes it.
+
+## Architecture
+
+The system consists of several integrated components:
+
+*   **Inbound Flow:** Internet → Cloudflare Email Routing → Inbound Worker → R2 Buffer → DockFlare Mail Manager Webhook → Local Storage.
+*   **Outbound Flow:** Webmail UI → Mail Manager API → Outbound Worker → Cloudflare `send_email` → Internet.
+*   **Data Sovereignty:** All emails are parsed and stored in a local SQLite database with attachments saved to your local filesystem.
+
+## Key Features
+
+*   **Multi-Domain Support:** Host email for as many domains as you manage in Cloudflare.
+*   **Edge Quota Enforcement:** Mailbox full? Cloudflare Workers reject the email at the SMTP level (5.2.2) before it even hits your server, saving bandwidth.
+*   **Full-Text Search:** Lightning-fast search across all your emails using SQLite FTS5.
+*   **Privacy First:** All API interactions use EdDSA JWT authentication. HTML email content is sanitized before rendering to prevent XSS and tracking pixels.
+*   **PWA Webmail:** A modern, mobile-responsive webmail client that can be installed on your phone or desktop.
+*   **Push Notifications:** Get notified of new mail in real-time via Web Push (VAPID).
+*   **Resilience:** If your server goes offline, Cloudflare R2 buffers your incoming mail and retries delivery automatically every 5 minutes.

dockflare/app/templates/docs/en/Email-Prerequisites.md

@@ -0,0 +1,30 @@
+# Email Prerequisites & Setup
+
+Before enabling the Email Suite, ensure your environment and Cloudflare account are properly configured.
+
+## Cloudflare Requirements
+
+1.  **Domain Management:** Your domain must be active on Cloudflare.
+2.  **Email Routing:** The domain must be eligible for Cloudflare Email Routing (available on most plans, including Free) and Cloudflare Email Sending (Beta Access required for outbound mail).
+3.  **R2 Storage:** You must have R2 enabled in your Cloudflare dashboard. R2 includes a free tier of 10 GB, but you may need to add a payment method to your account to activate it.
+
+## API Token Permissions
+
+The Email Suite requires additional permissions on your existing DockFlare API Token. Update it at **User Profile > API Tokens** and add the following permissions:
+
+| Scope | Specific Permission | Access Level | Purpose |
+| :--- | :--- | :--- | :--- |
+| **Account** | **Workers Scripts** | **Edit** | Deploying inbound/outbound workers |
+| **Account** | **Workers KV Storage** | **Edit** | Real-time quota enforcement at the edge |
+| **Account** | **R2 Storage** | **Edit** | Creating and managing transit buckets |
+| **Zone** | **Email Routing** | **Edit** | Activating routing and managing rules |
+| **Zone** | **DNS** | **Edit** | Creating MX, SPF, DMARC, and DKIM records |
+
+> **Security Note:** It is highly recommended to restrict this token's "Account Resources" and "Zone Resources" to only the specific account and domains you intend to use with DockFlare.
+
+## System Requirements
+
+*   **DockFlare:** v3.1.0 or later.
+*   **Docker:** v20.10+.
+*   **Docker Compose:** v2.20+ (required for `profiles` support).
+*   **Storage:** Ensure you have enough disk space on the host machine for the `mail_data` volume, which will store all email databases and attachments.

dockflare/app/templates/docs/en/Email-Using-Webmail.md

@@ -0,0 +1,33 @@
+# Using Webmail (PWA)
+
+DockFlare includes a modern, responsive webmail client that allows you to manage your emails from any device.
+
+## Accessing Webmail
+
+There are two ways to log in to Webmail:
+
+1.  **SSO (Single Sign-On):** If you are an admin logged into the DockFlare Master UI, click **Open Webmail** on the Email page. You will be automatically authenticated and logged into your mailboxes.
+2.  **Direct Login:** Navigate to `https://mail.yourdomain.com`. If you have set a password for your mailbox in the Master UI, you can log in directly using your email address and password.
+
+## Installing as a PWA
+
+The DockFlare Webmail is a **Progressive Web App (PWA)**. This means you can install it on your device for an app-like experience.
+
+### On Mobile (iOS/Android) (currently under development mobile support is limited)
+*   Open the webmail URL in your mobile browser.
+*   **iOS:** Tap the "Share" icon and select **Add to Home Screen**.
+*   **Android:** Tap the three dots and select **Install App** or **Add to Home Screen**.
+
+### On Desktop (Chrome/Edge/Brave)
+*   Look for the "Install" icon in the address bar (usually a small monitor with a down arrow).
+*   Click **Install**.
+
+## Key Features
+
+*   **Search:** Use the search bar to find emails. DockFlare uses Full-Text Search (FTS5) to index your subjects, senders, and message bodies locally.
+*   **Push Notifications:** Enable notifications in the Webmail settings to receive real-time alerts for new emails on your desktop or mobile device.
+
+## Security
+
+*   **EdDSA Authentication:** Webmail uses high-security Ed25519 JSON Web Tokens (JWT) issued by the DockFlare Master for all API interactions.
+*   **HTML Sanitization:** All incoming HTML emails are sanitized (using DOMPurify) before rendering to protect you from cross-site scripting (XSS) and tracking pixels.

dockflare/app/templates/docs/en/navigation.md

@@ -30,6 +30,14 @@ This documentation provides comprehensive information for DockFlare. Whether you
     *   [Understanding Graceful Deletion](Understanding-Graceful-Deletion.md)
     *   [Using the Web UI](Using-the-Web-UI.md)
     *   [Backup & Restore](Backup-and-Restore.md)
+*   **Email Suite**
+    *   [Overview & Architecture](Email-Overview.md)
+    *   [Prerequisites & CF Setup](Email-Prerequisites.md)
+    *   [Docker Deployment](Email-Docker-Deployment.md)
+    *   [Domain Configuration](Email-Domain-Setup.md)
+    *   [Mailbox & Quota Management](Email-Mailbox-Management.md)
+    *   [Using Webmail (PWA)](Email-Using-Webmail.md)
+    *   [Maintenance & Troubleshooting](Email-Maintenance.md)
 *   **Advanced Topics**
     *   [External `cloudflared` Mode](External-cloudflared-Mode.md)
     *   [Switching Between Modes](Switching-Between-Modes.md)