Skip to content
SAPA

Self-hosting

Self-hosting SAPA 0.1.x means operating a composition root that supplies every capability required by the workflows you use. SAPA does not operate a hosted service and does not currently ship a turnkey server.

Supported path

Section titled “Supported path”

The official path is to deploy the repository’s Cloudflare reference composition from source. It combines the Worker, D1, Queues, Workflows, R2, Cloudflare Access, dashboard assets, payment providers, and transactional email as one installation.

The concrete Cloudflare, storage, provider, and email adapters are not public npm packages in 0.1.0. Installing @byfungsi/sapa gives an Effect-native framework API, not the complete reference runtime.

Connect an application

Section titled “Connect an application”

There is no supported general-purpose SAPA HTTP client in 0.1.x. Integrate by calling public operations such as createCheckout and checkAccess inside your server-side Effect runtime after providing the required SapaService Layer.

Do not use /api/admin/* or /api/sandbox/* as application APIs. The first is an operator surface protected by Cloudflare Access; the second exists only in the isolated sandbox stage. The signed customer-action checkout route is purpose-specific and is not a replacement for authenticated merchant commands.

If your application and SAPA must run as separate services, you must define and own the production protocol, authentication, authorization, idempotency, rate limits, and versioning. That custom protocol is not yet a supported SAPA contract.

Custom infrastructure

Section titled “Custom infrastructure”

Other infrastructure targets are possible but unsupported until their adapters pass the same contracts and invariants as the reference installation. A custom composition must provide, as applicable:

  • cohesive atomic storage operations and guarded lifecycle transitions;
  • immutable commercial snapshots and verifiable authoritative history;
  • payment-provider authentication, stable creation identities, and recovery;
  • durable queues, leases, fencing, retries, and dead-letter handling;
  • request-scoped runtime resources rather than shared request handles;
  • clocks, identifiers, cryptography, key rotation, and secret redaction;
  • transactional email with idempotent delivery records;
  • bounded administrative reads and history verification;
  • signed, customer-bound, eligibility-bound, expiring download URLs;
  • one-time raw license-key disclosure without plaintext retention.

Never keep a database transaction open across provider, email, or other network work. Commit the authoritative decision and owed work atomically, then execute external work through a durable worker.

Installation identity and tenancy

Section titled “Installation identity and tenancy”

The reference deployment is single-installation-oriented. Keep SAPA_INSTALLATION_ID stable for the lifetime of its data. Do not repurpose one installation and its secrets as an implicit multi-tenant service.

Documentation hosting is separate

Section titled “Documentation hosting is separate”

This website is deployed by the private @sapa/docs Alchemy application at docs.usesapa.app. Deploying documentation does not deploy the SAPA Worker, migrate D1, change provider configuration, or publish @byfungsi/sapa to npm. Likewise, deploying the runtime does not publish or update these docs.