|
| 1 | +# Open-Temp-Mail Deployment Guide |
| 2 | + |
| 3 | +This guide provides step-by-step instructions to deploy the Open-Temp-Mail application to Cloudflare Workers. It covers everything from setting up your environment to rigorous verification. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +Before starting, ensure you have the following installed: |
| 8 | + |
| 9 | +1. **Node.js & npm**: Download and install from [Node.js official website](https://nodejs.org/). (Version 18 or higher recommended). |
| 10 | +2. **Git**: Download and install from [Git official website](https://git-scm.com/). |
| 11 | +3. **Cloudflare Account**: Sign up at [Cloudflare](https://dash.cloudflare.com/sign-up) if you don't have one. |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Automated Deployment (Recommended) |
| 16 | + |
| 17 | +We provide a script to automate the entire setup process. |
| 18 | + |
| 19 | +1. **Install & Login**: |
| 20 | + ```bash |
| 21 | + npm install -g wrangler |
| 22 | + wrangler login |
| 23 | + ``` |
| 24 | +2. **Run Setup**: |
| 25 | + ```bash |
| 26 | + cd "version 2" |
| 27 | + npm run deploy:setup |
| 28 | + ``` |
| 29 | + Follow the interactive prompts to set up your database, secrets, and deploy. |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## Manual Deployment |
| 34 | + |
| 35 | +If you prefer to set up everything manually, follow these steps. |
| 36 | + |
| 37 | +## Step 1: Install Wrangler CLI |
| 38 | + |
| 39 | +The Wrangler CLI is the command-line tool for building and managing Cloudflare Workers. |
| 40 | + |
| 41 | +1. Open your terminal (Command Prompt, PowerShell, or macOS Terminal). |
| 42 | +2. Install Wrangler globally: |
| 43 | + ```bash |
| 44 | + npm install -g wrangler |
| 45 | + ``` |
| 46 | +3. Verify the installation: |
| 47 | + ```bash |
| 48 | + wrangler --version |
| 49 | + ``` |
| 50 | + |
| 51 | +--- |
| 52 | + |
| 53 | +## Step 2: Login to Cloudflare |
| 54 | + |
| 55 | +Connect your local environment to your Cloudflare account. |
| 56 | + |
| 57 | +1. Run the login command: |
| 58 | + ```bash |
| 59 | + wrangler login |
| 60 | + ``` |
| 61 | +2. A browser window will open asking you to authorize Wrangler. |
| 62 | +3. Click **"Allow"**. |
| 63 | +4. Close the browser tab once you see the success message. |
| 64 | +5. In your terminal, you should see: `Successfully logged in`. |
| 65 | + |
| 66 | +--- |
| 67 | + |
| 68 | +## Step 3: Project Setup |
| 69 | + |
| 70 | +Navigate to the project directory and install dependencies. |
| 71 | + |
| 72 | +1. Open your terminal in the `version 2` folder of your project: |
| 73 | + ```bash |
| 74 | + cd "path/to/open-temp-mail" |
| 75 | + ``` |
| 76 | +2. Install project dependencies: |
| 77 | + ```bash |
| 78 | + npm install |
| 79 | + ``` |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +## Step 4: Create Cloudflare Resources |
| 84 | + |
| 85 | +You need two main resources: a **D1 Database** (for storing user/mailbox data) and an **R2 Bucket** (for storing full email contents). |
| 86 | + |
| 87 | +### 4.1 Create D1 Database |
| 88 | + |
| 89 | +1. Run the creation command: |
| 90 | + ```bash |
| 91 | + wrangler d1 create maill_free_db |
| 92 | + ``` |
| 93 | +2. **Copy the output!** You will see something like this: |
| 94 | + ```toml |
| 95 | + [[d1_databases]] |
| 96 | + binding = "DB" # i.e. available in your Worker on env.DB |
| 97 | + database_name = "maill_free_db" |
| 98 | + database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" |
| 99 | + ``` |
| 100 | +3. Open `wrangler.toml` in your text editor. |
| 101 | +4. Find the `[[d1_databases]]` section. |
| 102 | +5. Update the `database_id` with the one you just copied. **Do not change the `binding` name (`TEMP_MAIL_DB`)**, as the code relies on it. |
| 103 | + |
| 104 | +### 4.2 Initialize Database Schema |
| 105 | + |
| 106 | +Apply the database structure (tables) to your new D1 database. |
| 107 | + |
| 108 | +1. Run the execute command: |
| 109 | + ```bash |
| 110 | + wrangler d1 execute maill_free_db --file=d1-init.sql |
| 111 | + ``` |
| 112 | +2. Type `y` if prompted to confirm (for remote databases). |
| 113 | + |
| 114 | +### 4.3 Create R2 Bucket |
| 115 | + |
| 116 | +1. Run the create command: |
| 117 | + ```bash |
| 118 | + wrangler r2 bucket create mail-eml |
| 119 | + ``` |
| 120 | +2. Confirm it matches the `bucket_name` in your `wrangler.toml` (default is `mail-eml`). |
| 121 | + |
| 122 | +--- |
| 123 | + |
| 124 | +## Step 5: Configure Secrets |
| 125 | + |
| 126 | +Set up secure environment variables for your application. |
| 127 | + |
| 128 | +1. **Strict Admin Password** (Required): |
| 129 | + ```bash |
| 130 | + wrangler secret put ADMIN_PASSWORD |
| 131 | + # Enter your desired rigorous password when prompted |
| 132 | + ``` |
| 133 | + |
| 134 | +2. **JWT Signing Token** (Required): |
| 135 | + ```bash |
| 136 | + wrangler secret put JWT_TOKEN |
| 137 | + # Enter a long, random string (e.g., generated via `openssl rand -hex 32`) |
| 138 | + ``` |
| 139 | + |
| 140 | +3. **Resend API Key** (Optional, for sending emails): |
| 141 | + ```bash |
| 142 | + wrangler secret put RESEND_API_KEY |
| 143 | + # Enter your key from https://resend.com |
| 144 | + ``` |
| 145 | + |
| 146 | +--- |
| 147 | + |
| 148 | +## Step 6: Build and Deploy |
| 149 | + |
| 150 | +Now, build the frontend and deploy the full stack to Cloudflare. |
| 151 | + |
| 152 | +1. **Build the Frontend**: |
| 153 | + This compiles your React code into static assets in the `dist/` folder. |
| 154 | + ```bash |
| 155 | + npm run build |
| 156 | + ``` |
| 157 | + |
| 158 | +2. **Deploy to Cloudflare Workers**: |
| 159 | + This uploads your backend code and the static assets. |
| 160 | + ```bash |
| 161 | + wrangler deploy |
| 162 | + ``` |
| 163 | + |
| 164 | +3. **Success!** |
| 165 | + The terminal will output your Worker's URL, e.g., `https://open-temp-mail.your-subdomain.workers.dev`. |
| 166 | +
|
| 167 | +--- |
| 168 | +
|
| 169 | +## Step 7: Post-Deployment Configuration |
| 170 | +
|
| 171 | +### 7.1 Setup Email Routing (Catch-All) |
| 172 | +
|
| 173 | +To receive emails, you must configure Cloudflare Email Routing. |
| 174 | +
|
| 175 | +1. Go to the [Cloudflare Dashboard](https://dash.cloudflare.com/). |
| 176 | +2. Select your domain. |
| 177 | +3. Navigate to **Email** > **Email Routing**. |
| 178 | +4. Click **"Get Started"** if not already enabled. |
| 179 | +5. Go to the **Routes** tab. |
| 180 | +6. Click **Create Custom Address**. |
| 181 | + - **Custom Address**: Enter `*` (Catch-all) to receive emails for any address (e.g., `anything@yourdomain.com`). |
| 182 | + - **Action**: `Send to a Worker`. |
| 183 | + - **Destination**: Select your newly deployed Worker (`open-temp-mail`). |
| 184 | +7. Click **Save**. |
| 185 | +
|
| 186 | +### 7.2 Verify Deployment |
| 187 | +
|
| 188 | +1. Open your Worker URL in a browser. |
| 189 | +2. You should see the Open-Temp-Mail login page. |
| 190 | +3. Login with `admin` and the password you set in **Step 5**. |
| 191 | +4. Try creating a random mailbox to test database connectivity. |
| 192 | +5. Try sending an email to that mailbox (from an external account like Gmail) to test Email Routing. |
| 193 | +
|
| 194 | +--- |
| 195 | +
|
| 196 | +## Troubleshooting |
| 197 | +
|
| 198 | +- **Frontend loads blank**: Open your browser's Developer Tools (F12) -> Console. Check for errors. |
| 199 | +- **Database errors**: Ensure you ran the `d1 execute` command (Step 4.2). |
| 200 | +- **"Uncaught (in promise)"**: Check your `wrangler secret list` to ensure all secrets are set. |
| 201 | +- **Email not received**: Verify your domain's MX records in Cloudflare DNS settings match what Email Routing requires. |
| 202 | +
|
| 203 | +--- |
| 204 | +
|
| 205 | +## Local Development |
| 206 | +
|
| 207 | +You can run the application locally in two modes: **Local Mode** (using a local temporary database) or **Remote Mode** (connecting to your live Cloudflare D1 database). |
| 208 | +
|
| 209 | +### Option 1: Local Backend (Default) |
| 210 | +*Use this for safe development without affecting production data.* |
| 211 | +
|
| 212 | +1. **Start Frontend**: |
| 213 | + ```bash |
| 214 | + npm run dev |
| 215 | + ``` |
| 216 | + (Runs on `http://localhost:5173`) |
| 217 | +
|
| 218 | +2. **Start Backend** (in a new terminal): |
| 219 | + ```bash |
| 220 | + npm run dev:backend |
| 221 | + ``` |
| 222 | + (Runs on `http://localhost:8787` using a local SQLite file) |
| 223 | +
|
| 224 | +### Option 2: Remote Backend (Live Data) |
| 225 | +*Use this to debug with your actual production database.* |
| 226 | +
|
| 227 | +1. **Start Frontend**: |
| 228 | + ```bash |
| 229 | + npm run dev |
| 230 | + ``` |
| 231 | +
|
| 232 | +2. **Start Backend** (in a new terminal): |
| 233 | + ```bash |
| 234 | + npm run dev:backend:remote |
| 235 | + ``` |
| 236 | + (Runs on `http://localhost:8787` but connects to your generic Cloudflare D1 DB) |
| 237 | +
|
0 commit comments