Merge pull request #537 from constructive-io/anmol/jobs-doc-cleanup

docs: update readme

Author: Anmol1696

jobs/DEVELOPMENT_JOBS.md

@@ -110,65 +110,18 @@ This starts:
 
 ### Switching dry run vs real Mailgun sending
 
-By default, `docker-compose.jobs.yml` runs both email functions in dry-run mode (no real email is sent), and it uses placeholder Mailgun credentials unless you provide `MAILGUN_API_KEY` / `MAILGUN_KEY`.
+By default, `docker-compose.jobs.yml` runs both email functions in dry-run mode (no real email is sent), and it uses placeholder Mailgun credentials.
 
-Quick start commands:
-
-Dry run:
+Dry run (recommended for local development):
 
 ```sh
 docker compose -f docker-compose.jobs.yml up -d --build --force-recreate
 ```
 
-Real sending (Mailgun):
-
-```sh
-MAILGUN_API_KEY="your-mailgun-key" MAILGUN_KEY="your-mailgun-key" SIMPLE_EMAIL_DRY_RUN=false SEND_EMAIL_LINK_DRY_RUN=false docker compose -f docker-compose.jobs.yml up -d --build --force-recreate
-```
-
-To use a real Mailgun key without editing `docker-compose.jobs.yml`, set these env vars before starting the stack (or put them in a local `.env` file in the `constructive/` directory). Don't commit your `.env`.
-
-```sh
-export MAILGUN_API_KEY="your-mailgun-key"
-export MAILGUN_KEY="your-mailgun-key"
-```
-
-If you're not using `mg.constructive.io`, also override `MAILGUN_DOMAIN`, `MAILGUN_FROM`, and `MAILGUN_REPLY` (for example in the override file below) to match your Mailgun setup.
-
-To actually send email (instead of dry-run), set these env vars (or put them in your local `.env`):
-
-```sh
-export SIMPLE_EMAIL_DRY_RUN=false
-export SEND_EMAIL_LINK_DRY_RUN=false
-```
-
-Then recreate the stack so the new env is applied:
-
-```sh
-docker compose -f docker-compose.jobs.yml up -d --build --force-recreate
-```
-
-If you prefer not to export env vars, create a local override file (don't commit it) at `docker-compose.jobs.override.yml`:
-
-```yml
-services:
-  simple-email:
-    environment:
-      SIMPLE_EMAIL_DRY_RUN: "false"
-
-  send-email-link:
-    environment:
-      SEND_EMAIL_LINK_DRY_RUN: "false"
-```
-
-Start the stack with both files:
-
-```sh
-docker compose -f docker-compose.jobs.yml -f docker-compose.jobs.override.yml up -d --build --force-recreate
-```
-
-To switch back to dry-run, set `SIMPLE_EMAIL_DRY_RUN=true` and `SEND_EMAIL_LINK_DRY_RUN=true` (or delete the override file) and recreate again.
+In dry-run mode:
 
+- The `simple-email` and `send-email-link` containers log the payload they would send instead of hitting Mailgun.
+- You should see log lines like `[simple-email] DRY RUN email (skipping send) ...` and `[send-email-link] DRY RUN email (skipping send) ...`.
 ---
 
 ## 5. Ensure GraphQL host routing works for `send-email-link`
@@ -295,3 +248,58 @@ To stop everything, including Postgres and Minio:
 ```sh
 docker compose down
 ```
+
+---
+
+## 10. Optional Mailgun secrets for real sending
+
+Real Mailgun credentials are **not required** to run the jobs stack locally; they are only needed if you want to send real email in development instead of using dry-run logging.
+
+To start the stack with real sending from the command line:
+
+```sh
+MAILGUN_API_KEY="your-mailgun-key" MAILGUN_KEY="your-mailgun-key" SIMPLE_EMAIL_DRY_RUN=false SEND_EMAIL_LINK_DRY_RUN=false docker compose -f docker-compose.jobs.yml up -d --build --force-recreate
+```
+
+Alternatively, you can set the secrets in your shell or a local `.env` file (do not commit this file) in the `constructive/` directory:
+
+```sh
+export MAILGUN_API_KEY="your-mailgun-key"
+export MAILGUN_KEY="your-mailgun-key"
+```
+
+If you're not using `mg.constructive.io`, also override `MAILGUN_DOMAIN`, `MAILGUN_FROM`, and `MAILGUN_REPLY` (for example in an override file) to match your Mailgun setup.
+
+To have the containers send real email instead of dry-run, set:
+
+```sh
+export SIMPLE_EMAIL_DRY_RUN=false
+export SEND_EMAIL_LINK_DRY_RUN=false
+```
+
+Then recreate the stack so the new env is applied:
+
+```sh
+docker compose -f docker-compose.jobs.yml up -d --build --force-recreate
+```
+
+If you prefer not to export env vars, create a local override file (don't commit it) at `docker-compose.jobs.override.yml`:
+
+```yml
+services:
+  simple-email:
+    environment:
+      SIMPLE_EMAIL_DRY_RUN: "false"
+
+  send-email-link:
+    environment:
+      SEND_EMAIL_LINK_DRY_RUN: "false"
+```
+
+Start the stack with both files:
+
+```sh
+docker compose -f docker-compose.jobs.yml -f docker-compose.jobs.override.yml up -d --build --force-recreate
+```
+
+To switch back to dry-run, set `SIMPLE_EMAIL_DRY_RUN=true` and `SEND_EMAIL_LINK_DRY_RUN=true` (or delete the override file) and recreate again.

jobs/README.md

@@ -156,7 +156,7 @@ http://simple-email.interweb.svc.cluster.local
 and the worker will call:
 
 ```text
-POST http://simple-email.interweb.svc.cluster.local/simple-email
+POST http://simple-email.interweb.svc.cluster.local/
 ```
 
 ---