> ## Documentation Index
> Fetch the complete documentation index at: https://www.activepieces.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Building for Self-Hosting

We develop against Cloud, where every env var, secret, and key is already provisioned. Most of our users self-host. When a feature quietly depends on something only Cloud has, it works on your machine, in the demo, and in the changelog — and is **silently broken for everyone who self-hosts.** They see a feature that looks enabled, doesn't work, and tells them nothing. Then they open a ticket.

## The core rule: default to zero-setup

> If a feature needs the self-hoster to set something up first, the default is **make it work with zero setup** — not "document the env var."

An env var isn't a feature flag for the user. It's a tax on every install, and an undiscoverable failure: they enable the feature, it fails, nothing explains why. Order of preference for any required secret/key/config:

1. **Auto-provision** it on first boot or first use. Reach for this first — it's almost always possible.
2. **Derive** it from something the instance already has.
3. **Gate visibly** — if the prerequisite is genuinely absent, the feature must be **disabled with an explanation**, never enabled-but-broken.
4. **Require manual setup** — last resort only, with a clear in-product error *and* a changelog note.

## Failure modes we keep hitting

**1. "Requires manual setup" shipped as enabled.** A feature needs a per-instance key. Cloud has it, so it works; self-hosters don't, so it fails — but the UI shows it as available.

* *S3 IAM Role / OIDC (PR #13439)* depends on `AP_OIDC_RSA_PRIVATE_KEY`. Unset, every connection fails: `/api/v1/worker/oidc-token` → `400`, `/.well-known/jwks.json` → `400 SYSTEM_PROP_INVALID`. The discovery doc returns `200`, so it *looks* deployed. The fix is to **auto-generate the key**, not document the env var.
* *Pipefy* shipped the same shape — enabled in the UI, broken until an undocumented setup step is done.

**2. Data-layer changes that break self-hosted upgrades.** *pgvector:* we added a dependency on the extension. Cloud's Postgres had it; many self-hosted instances didn't. Upgrades failed on migration — and it never reached breaking-changes, *because the people who hit it self-host and we don't test that path.* Either don't depend on what self-hosted Postgres may lack, or flag it as breaking, fail the migration with an actionable error, and document the step.

**3. Assuming Cloud's network and infra.** Cloud has outbound internet, a public webhook URL, and generous resources. Self-hosters may run air-gapped or in strict network mode, behind a firewall with no public URL, or on tighter limits. A feature that calls an external service at runtime, fetches from a registry, assumes a publicly reachable callback, or hardcodes a Cloud URL (`cloud.activepieces.com`, `api.activepieces.com`) works for us and dies for them. Degrade gracefully when a dependency is absent, and derive URLs from the instance's own config — never hardcode Cloud's.

**4. Enabling a feature without a self-hosted path at all.** A capability is built on a Cloud-only service (a managed secret store, a proprietary backend, a paid third-party with our key) and exposed everywhere anyway. Self-hosters can't supply the missing half, so it can never work for them. Decide up front whether it has a self-hosted story — if not, gate it by edition rather than letting it surface broken.

## If it genuinely can't be zero-setup

The UI must never present the feature as working when it isn't.

* **Disable it visibly** with a message naming the missing prerequisite. Use existing patterns (`LockedFeatureGuard`, `enabled:` on queries, `platformMustHaveFeatureEnabled`).
* **Fail with a real error** that names the prerequisite and links the fix — not an opaque `400`.
* "Disable on Cloud" is a stopgap, not the goal. We want it to *work everywhere*, not be hidden on the one env where it happens to be set up.

We're self-hosting-first. The self-hosted non-happy path *is* the happy path for most users — building for it is the work, not extra work.