warmbly/docs/VENDOR_LOCKIN.md

Vendor Lock-in Audit

Honest accounting of where Warmbly does and doesn't lock you into a specific cloud / SaaS provider. Status as of the pluggable-backends refactor.

TL;DR

• Workers: zero vendor lock-in. A worker runs on any Linux box with outbound HTTPS + SMTP/IMAP. No AWS, no GCP, no Stripe SDK, nothing.
• Backend: mostly self-hostable. Six pluggable interfaces (KMS, encrypted keys, blob store, event bus, codec, cache) all ship with self-hostable implementations. Three remaining concerns still pin to specific vendors: task scheduling, captcha, and payments. All three are optional in the sense that you can run the platform with them stubbed; payments + captcha are only needed if you're running a public SaaS.

The pluggable layer (no lock-in)

Concern	Interface	Self-host default	AWS / cloud option	Other options
KMS / root key	kms.Provider	local (AES-256-GCM, key from env/file)	aws-kms	Add vault, gcp-kms, azure-keyvault by implementing the interface
Encrypted DEKs	encryptedkeys.Store	postgres (backend) / http (worker)	n/a — postgres works everywhere	Add dynamodb, etcd, etc. by implementing the Store interface
Blob storage	storage.Store	filesystem	s3 (AWS)	One s3 impl also works for MinIO, Cloudflare R2, Backblaze B2, Hetzner Object Storage — set AWS_ENDPOINT_URL_S3
Event bus	eventbus.EventBus	nats (JetStream)	kafka	Redis Streams, etc. by implementing the interface
Codec	codec.Codec	json	avro (requires Schema Registry)	Protobuf etc.
Cache	(*cache.Cache)	Redis (any Redis-compatible: Valkey, KeyDB)	Redis	Could be abstracted further if needed
Internal HTTP auth	bearer token	Self-issued via openssl rand -base64 32	n/a	JWT-per-worker is the planned follow-up

Selection is per-process via env vars (KMS_PROVIDER, BLOB_PROVIDER, EVENTBUS_PROVIDER, etc.). Every selector has a self-hostable default; AWS is not the implicit fall-through except for KMS where the historical default is preserved for the hosted Warmbly install.

See docs/INTERNAL_API_AUTH.md for the worker → backend auth model.

What's still vendor-pinned

1. Task scheduling: Google Cloud Tasks

What: internal/infrastructure/gtasks/gtasks.go schedules deferred work (send this email at 9am, retry this in 30 min, etc.).

Why it matters: Required by the backend if you want scheduled cold campaigns and warmup pacing.

Self-hostable today? Partial. The local dev stack uses google/cloud-tasks-emulator (open-source emulator) so you can run end-to-end without GCP. The same emulator works in production if you self-host it (a Java service from Google's own repo).

True lock-in? Yes for production hosted on cloud. A native replacement would be:

• Embed a simple time-wheel scheduler in the backend using Postgres for state
• Use a job queue like River, Asynq, or Faktory
• Use Postgres LISTEN/NOTIFY + a polling worker

Any of these would be ~1 week of focused work. Not done because the existing GCP emulator is a "good enough" self-host path for now.

2. Captcha: Cloudflare Turnstile

What: internal/pkg/captcha/turnstile.go protects signup / login / password reset against bot abuse.

Why it matters: Only relevant for public SaaS where you accept signups from the world. An internal-only Warmbly instance (e.g., one agency, one team) doesn't need it.

Self-hostable today? Effectively yes if you set AUTH_TURNSTILE_BYPASS_TOKEN to a value your forms always send — the captcha check passes through. Suitable for trusted single-tenant deploys.

True lock-in? Soft. Cloudflare Turnstile is free and works against any origin. If you genuinely need a captcha and don't want CF, replace it with hCaptcha or a self-hosted alternative like ALTCHA — same shape, different SDK.

3. Payments: Stripe

What: internal/app/stripe/service.go and related — subscription plans, billing portal, webhook handling.

Why it matters: Only relevant for SaaS that charges money. A self-hosted Warmbly that's free or licensed by lump sum doesn't need it.

Self-hostable today? Yes by not configuring Stripe credentials — the service no-ops on missing config and the relevant admin pages hide.

True lock-in? Soft. Same shape applies — swap Stripe for LemonSqueezy, Paddle, or your own billing if you want. The repo doesn't go out of its way to be Stripe-specific outside of internal/app/stripe/.

4. Secrets loader: AWS Secrets Manager / SSM

What: cfg.LoadXxx() calls in internal/config/ pull config from AWS Secrets Manager / SSM. Used for production hosted Warmbly so secrets don't sit in env files.

Self-hostable today? Yes — all callers fall back to plain env vars when the AWS lookup fails. Self-hosters set env vars; AWS-hosted reads from Secrets Manager. Same code path, different source.

True lock-in? None for self-hosters. The AWS path exists, but it's not required.

5. Geo IP database

What: internal/infrastructure/geo/ loads a MaxMind-format GeoIP DB for IP-based location lookups (admin views, abuse detection).

Self-hostable today? Yes. Operator drops a MaxMind GeoLite2 database (free) at the configured path. Works fully offline.

True lock-in? None. Open data format, multiple sources.

6. Sentry (error reporting)

Self-hostable today? Yes. Sentry has a self-host offering. Set SENTRY_DSN to point at it or leave it unset to disable.

True lock-in? None.

What a fully self-hosted Warmbly looks like

Minimum viable stack (no clouds required):

┌────────────────────────────────────────────────────────────────┐
│ Single VPS or small fleet                                      │
│                                                                │
│ ┌──────────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│ │   Backend    │  │ Consumer │  │  Worker  │  │ Tracking │    │
│ │   (Go)       │  │  (Go)    │  │  (Go)    │  │  (Rust)  │    │
│ └──────┬───────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘    │
│        │               │              │              │         │
│        ├───────────────┴──────┬───────┘              │         │
│        │                      │                      │         │
│        ▼                      ▼                      ▼         │
│ ┌──────────────┐  ┌─────────────────┐  ┌─────────────────────┐│
│ │  PostgreSQL  │  │      NATS       │  │  Local filesystem   ││
│ │  (primary    │  │   JetStream     │  │  (blob store) +     ││
│ │   DB +       │  │   (event bus)   │  │   AES key file      ││
│ │   DEK store) │  │                 │  │   (local KMS)       ││
│ └──────────────┘  └─────────────────┘  └─────────────────────┘│
│                                                                │
│        ┌─────────────────┐                                     │
│        │      Redis      │  ← cache (any Redis-compatible)     │
│        └─────────────────┘                                     │
└────────────────────────────────────────────────────────────────┘

      Outbound: SMTP/IMAP to mailbox providers + HTTPS to AI APIs
      No required calls to AWS / GCP / Stripe / Cloudflare

Env-var configuration for this stack:

KMS_PROVIDER=local
KMS_LOCAL_MASTER_KEY=$(openssl rand -base64 32)

ENCRYPTED_KEYS_PROVIDER=postgres   # backend
ENCRYPTED_KEYS_PROVIDER=http       # worker
ENCRYPTED_KEYS_BACKEND_URL=https://api.yourdomain.com
ENCRYPTED_KEYS_WORKER_TOKEN=...    # same as INTERNAL_API_TOKEN
INTERNAL_API_TOKEN=$(openssl rand -base64 32)

BLOB_PROVIDER=filesystem
BLOB_FS_ROOT=/var/lib/warmbly/blobs

EVENTBUS_PROVIDER=nats
NATS_URL=nats://nats.local:4222

CODEC_PROVIDER=json   # if you don't want Schema Registry

# Optional / for SaaS only:
# STRIPE_SECRET_KEY=...
# AUTH_TURNSTILE_SECRET=...
# CLOUD_TASKS_QUEUE_NAME=...

Status by component

Component	Self-host ready?	Notes
Backend API (Go)	✅ yes	Run on any Linux/Docker host
Consumer (Go)	✅ yes	Same
Worker (Go)	✅ yes	No DB, just outbound HTTPS + SMTP/IMAP
Tracking (Rust)	✅ yes	Standalone HTTP service
Realtime (Elixir)	✅ yes	Standalone Phoenix service
Admin UI (admin/)	✅ yes	Vite build, deploy as static files
Dashboard (web/)	✅ yes	Same
Postgres	✅ yes	Any 14+ install
Redis	✅ yes	Or Valkey, KeyDB
NATS JetStream	✅ yes	Single binary, ~20MB
Kafka (optional)	✅ yes	For Avro / Schema Registry preference
KMS	✅ yes	Local impl; AWS/GCP/Vault by config
Blob store	✅ yes	Filesystem; or any S3-compatible
Encrypted DEK store	✅ yes	Postgres
Task scheduling	⚠ partial	Needs Cloud Tasks emulator self-hosted
Captcha	⚠ optional	Bypass-token mode for trusted deploys
Payments	⚠ optional	Stripe — only if you charge
Sentry	⚠ optional	Or self-hosted Sentry, or off

The "⚠ partial / optional" rows are the only places a clean-room self-hoster has to make a deliberate operational choice. Everything else just works.