feat(self-host): SMTP/BunMail email, Docker stack, and MinIO presigned URL fixes

[raedbrahem]

Summary

Self-hosted deployment improvements from production use of Comp on Docker:

• Email transport: Optional SMTP and BunMail REST transports, with direct send when TRIGGER_SECRET_KEY is unset (no Trigger.dev required for basic email).
• Docker Compose: Adds api service, optional MinIO profile (docker compose --profile minio up), build args for NEXT_PUBLIC_API_URL / portal URL, and local Postgres hostname support (comp-postgres).
• Dockerfile: Build migrator/seeder from local packages/db source; Prisma seed via Node/tsx; workspace package build order fixes.
• Portal links: Central getPortalBaseUrl() helper so emails and invites respect PORTAL_URL on self-hosted installs.
• S3/MinIO: APP_AWS_PUBLIC_ENDPOINT for browser-reachable presigned URLs when the internal endpoint is not reachable from clients.
• Device agent download: Buffer-based S3 response handling for compatibility with MinIO.

Motivation

The upstream Docker guide assumes Resend + Trigger.dev + external Postgres. These changes make a fully self-contained Docker stack workable for teams that prefer SMTP/BunMail and optional local MinIO, without changing cloud behavior when those env vars are unset.

Test plan

• docker compose build app portal api succeeds with exported BETTER_AUTH_URL / NEXT_PUBLIC_API_URL build args
• With TRIGGER_SECRET_KEY unset and SMTP_HOST set, invitation/policy emails send directly
• With docker compose --profile minio up, evidence upload and attachment download work when APP_AWS_ENDPOINT=http://minio:9000 and APP_AWS_PUBLIC_ENDPOINT points to a browser-reachable host
• Cloud path unchanged: Resend + Trigger.dev still used when configured

Notes

• MinIO services are behind the minio Compose profile so existing deployments are unaffected.
• No org-specific domains, credentials, or infrastructure details are included in this PR.

Made with Cursor

---

Summary by cubic

Adds self‑hosted email and a fuller Docker stack: optional BunMail REST and SMTP transports with direct send when TRIGGER_SECRET_KEY is unset, api service wired into Compose, optional MinIO, and safer presigned URLs. Also centralizes portal links and respects sslmode=disable for local Postgres across apps and tools.

• New Features

  • Email: Adds BunMail REST and SMTP; sends directly if TRIGGER_SECRET_KEY is unset; scheduled sends route to Resend only (errors if unavailable); uses BunMail for normal sends and falls back to SMTP/Resend for attachments; adds one‑click List‑Unsubscribe headers.
  • Docker: Adds api service (port 3333) with health checks and NEXT_PUBLIC_API_URL build args; migrator seeds via Node/tsx; optional minio profile pins images and auto‑creates the bucket.
  • S3/MinIO: Uses APP_AWS_PUBLIC_ENDPOINT only for signing browser‑reachable presigned URLs; portal agent downloads stream via transformToWebStream().
  • URLs/TLS: Central getPortalBaseUrl() used in app/API/emails; honors sslmode=disable in DATABASE_URL across app, portal, API, framework editor, and DB tools.

• Migration

  • Email: set BUNMAIL_API_URL, BUNMAIL_API_KEY, BUNMAIL_FROM (takes priority), or SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASS, SMTP_FROM.
  • MinIO: run with docker compose --profile minio up; set APP_AWS_ENDPOINT (internal), APP_AWS_PUBLIC_ENDPOINT (browser), MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, APP_AWS_BUCKET_NAME.
  • URLs: set PORTAL_URL and NEXT_PUBLIC_API_URL.
  • Scheduling: leave TRIGGER_SECRET_KEY unset for direct sends (no scheduling), or set it to enable scheduled emails via Resend/Trigger.dev.

^{Written for commit 7af047b. Summary will update on new commits.}

[CLAassistant]

All committers have signed the CLA.

[cubic-dev-ai]

1 issue found and verified against the latest diff

Confidence score: 3/5

• In packages/db/src/ssl-config.ts, the hostname handling fix is not applied for framework-editor and combine-schemas.js-emitted clients, so comp-postgres can still be treated as remote and plain Docker Postgres/self-hosted connections may use the wrong SSL behavior and fail to connect — apply the same hostname classification logic across all client creation paths and add a regression test for those emitters.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/db/src/ssl-config.ts">

<violation number="1" location="packages/db/src/ssl-config.ts:6">
P2: Self-hosted connections made through the framework-editor client or a client emitted by `combine-schemas.js` still treat `comp-postgres` as remote, so this hostname fix is not applied consistently and plain Docker Postgres connections can fail TLS negotiation. Keeping the hostname classification synchronized in the generated-client template and every Prisma client would make the self-hosted behavior consistent.

(Based on your team's feedback about generated Prisma client configuration and coordinated call sites.)</violation>
</file>

<sub>Tip: instead of fixing issues one by one fix them all with cubic
Tip: cubic used a learning from your PR history. Let your coding agent read cubic learnings directly with the cubic MCP.

Re-trigger cubic</sub>

[raedbrahem]

Thanks for the review — pushed commit 0df2e54 addressing the cubic feedback:

Email transport

• Decode Trigger task base64 attachment payloads before SMTP send
• Removed global RESEND_TO_TEST redirect from centralized transport
• BunMail falls back to SMTP/Resend when attachments, custom headers, or scheduling are required
• Reject scheduledAt sends when TRIGGER_SECRET_KEY is unset
• Extracted shared buildUnsubscribeHeaders() helper

Portal URLs

• Reused getPortalBaseUrl() in no-access page and invite service
• Removed redundant trailing-slash strip in policy digest email

Docker / MinIO

• Portal build arg uses documented NEXT_PUBLIC_API_URL
• Pinned MinIO/mc image tags; require MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, and APP_AWS_BUCKET_NAME (no default credentials)
• minio-init verifies bucket with mc stat before reporting success

DB TLS

• Removed hardcoded comp-postgres hostname bypass; sslmode=disable in DATABASE_URL is the explicit opt-out

Other

• Device agent download streams via transformToWebStream() again
• Migrator installs pinned tsx@4.19.3 via Bun instead of npm global

CLA signing is still pending on my side — will complete that separately.

[cubic-dev-ai]

1 issue found across 16 files (changes from recent commits).

Confidence score: 5/5

• In apps/api/src/email/send-batch-email.ts, unsubscribe URL/header construction is still duplicated instead of using buildUnsubscribeHeaders() from apps/api/src/email/unsubscribe-headers.ts, which creates a drift risk where future updates could make batch emails behave differently for one-click unsubscribe and cause subtle compliance/user-experience inconsistencies — route batch sending through the shared helper to keep behavior centralized.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/api/src/email/unsubscribe-headers.ts">

<violation number="1" location="apps/api/src/email/unsubscribe-headers.ts:3">
P3: The PR extracts buildUnsubscribeHeaders() to share one-click unsubscribe logic, but send-batch-email.ts still inlines the exact same URL/header construction instead of calling the new helper. Two copies of the unsubscribe URL logic now drift independently; recommend updating send-batch-email.ts to use buildUnsubscribeHeaders(email.to) so the shared helper is actually the single source of truth.</violation>
</file>

<sub>Tip: instead of fixing issues one by one fix them all with cubic
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The PR extracts buildUnsubscribeHeaders() to share one-click unsubscribe logic, but send-batch-email.ts still inlines the exact same URL/header construction instead of calling the new helper. Two copies of the unsubscribe URL logic now drift independently; recommend updating send-batch-email.ts to use buildUnsubscribeHeaders(email.to) so the shared helper is actually the single source of truth.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/api/src/email/unsubscribe-headers.ts, line 3:

<comment>The PR extracts buildUnsubscribeHeaders() to share one-click unsubscribe logic, but send-batch-email.ts still inlines the exact same URL/header construction instead of calling the new helper. Two copies of the unsubscribe URL logic now drift independently; recommend updating send-batch-email.ts to use buildUnsubscribeHeaders(email.to) so the shared helper is actually the single source of truth.</comment>

<file context>
@@ -0,0 +1,12 @@
+import { generateUnsubscribeToken } from '@trycompai/email';
+
+export function buildUnsubscribeHeaders(to: string): Record<string, string> {
+  const apiBaseUrl =
+    process.env.NEXT_PUBLIC_API_URL || 'https://api.trycomp.ai';
</file context>

[raedbrahem]

Pushed 30114013d addressing the second cubic review:

• BunMail: List-Unsubscribe headers no longer force SMTP/Resend fallback — BunMail works for standard triggerEmail flows again
• Scheduling: scheduledAt routes to Resend only; throws if Resend unavailable (prevents immediate SMTP delivery)
• S3 presigning: Caller-provided client preserved unless APP_AWS_PUBLIC_ENDPOINT is explicitly set
• MinIO profile: Env validation moved to container startup (default docker compose up works without MinIO vars)
• Migrator: Node.js runtime restored for tsx seeding; still installs pinned tsx@4.19.3 via Bun
• DB TLS: sslmode=disable handling synced to framework-editor client and combine-schemas.js emitter
• Unsubscribe: Trim trailing slash from API base URL; batch email task reuses buildUnsubscribeHeaders()

[cubic-dev-ai]

All reported issues were addressed across 9 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[raedbrahem]

Pushed 7af047bfd for the third cubic review:

• combine-schemas.js: malformed DATABASE_URL no longer disables TLS via substring localhost match
• Dockerfile: pinned Node 22.13.1 copied from official node:22.13.1-bookworm-slim (no curl|bash NodeSource installer)
• S3 comments: clarified APP_AWS_PUBLIC_ENDPOINT only affects presigning when explicitly set
• docker-compose: removed compose-time :? on APP_AWS_BUCKET_NAME in minio-init (runtime validation only)