Self-hosting
Choose and verify a database, storage driver, and job backend deliberately.
- Documentation owner:
- BlendDuck Documentation
- Last reviewed:
BlendDuck is one deployable TanStack Start application. The dashboard, authentication, native API handlers, MCP server, jobs, and data layer do not require a separate CMS or application backend.
Local single-instance profile
The verified local quickstart uses:
export DB_DIALECT=sqlite
export SQLITE_PATH=./wooply.db
export STORAGE_DRIVER=local
export JOBS_BACKEND=inline
pnpm db:deploy
pnpm dev
SQLite, local storage, and inline jobs are appropriate for local development and controlled single-process use. They are not a horizontal-production profile.
Database
| Dialect | Required setting | Intended use |
|---|---|---|
| PostgreSQL | DB_DIALECT=pg plus DATABASE_URL | Shared and multi-instance production |
| SQLite | DB_DIALECT=sqlite plus SQLITE_PATH | Local and single-instance environments |
| Cloudflare D1 | DB_DIALECT=d1 plus the D1 binding | Cloudflare Worker deployments |
Set DB_DIALECT explicitly. BlendDuck does not silently switch databases when
a connection fails.
Apply the migration set for the selected runtime:
pnpm db:deploy
Cloudflare production applies the reviewed SQLite-compatible migrations to the remote D1 database explicitly:
pnpm db:d1:migrate
Object storage
Choose local, s3, or r2 with STORAGE_DRIVER. Local storage is unsuitable
for horizontally scaled or ephemeral deployments. S3-compatible browser
uploads require bucket CORS for PUT from the exact APP_URL origin with the
Content-Type header.
Jobs
Use JOBS_BACKEND=inline for the verified local path. Select the configured
durable job integration for retries or execution that must survive the request
process. Scheduled-job recovery and publishing retries remain persisted even
when the execution backend changes.
Authentication and external origin
APP_URL is the canonical Better Auth, social callback, and MCP OAuth origin.
Production requires one public HTTPS origin, and reverse proxies must preserve
the original host/protocol plus authorization and MCP protocol headers.
Development email OTP is written to the server console only when no email
provider is configured. Production requires RESEND_API_KEY and EMAIL_FROM.
Security material
Back up ENCRYPTION_KEY securely. It encrypts stored provider credentials and
must remain independent from BETTER_AUTH_SECRET. Configure both through the
deployment secret store, not a committed environment file.
Verification
Use Quickstart for an end-to-end first run. Verify both the Node or Cloudflare build and each external provider connection you intend to use; a successful application build cannot validate provider credentials or platform-review state.