Skip to main content

Infrastructure adapters

Infrastructure adapters

info

Most teams use the default Install Compose stack and never touch adapter settings. This page is for higher-scale or custom deployments, external object storage, a CDN in front of downloads, or splitting the API and worker.

Patch is an integrated product, not a plugin marketplace. Under the hood it has two fixed integration points, storage adapters and delivery adapters, that let you swap backends without changing the CLI, dashboard, or SDK.

See How it works for the end-to-end flow. This page explains what you can configure on the server side.

Two layers​

LayerQuestion it answersEnv var
Storage adapterWhere are bundles and manifests stored?STORAGE_ADAPTER
Delivery adapterWhat public URLs do clients download from, and how is the cache invalidated?DELIVERY_ADAPTER

The API and worker read and write artifacts through the storage adapter. When a release is published, the delivery adapter resolves stable public URLs (embedded in manifests) and optionally purges a CDN cache.

The server never serves OTA artifacts from the API domain; clients fetch from your download base URL. See How delivery works.

Defaults (self-host installer)​

scripts/selfhost/install.sh sets up:

  • STORAGE_ADAPTER=s3 with bundled MinIO
  • DELIVERY_ADAPTER=base-url: clients fetch directly from PUBLIC_BASE_URL
  • PUBLIC_BASE_URL on your storage domain, e.g. https://storage.updates.example.com/codemagic-patch
  • Compose hardcodes MODE=all (API and release worker in one process)

That single-host layout is the supported self-host path. The Compose file also hardcodes the MinIO endpoint and bucket for the server service, so pointing at external object storage, or splitting MODE=api / MODE=worker, means a customized deployment, not only editing .env.selfhost.

Storage adapter​

Controls where release artifacts live.

ValueTypical use
s3Default. MinIO in the Compose stack, or any S3-compatible store (AWS S3, Cloudflare R2, etc.) in a custom deployment
gcsGoogle Cloud Storage with separate public and internal buckets (custom deployment)
memoryLocal development and tests only, not for production

S3-compatible storage​

Used by the default self-host stack (MinIO) and for external object storage at scale.

Key variables (full list in Configuration reference):

VariableRole
S3_BUCKETBucket name (required when STORAGE_ADAPTER=s3)
S3_ENDPOINTCustom endpoint for MinIO or S3-compatible services
S3_FORCE_PATH_STYLEtrue for MinIO; often false for AWS
S3_REGIONAWS region (default us-east-1)
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEYCredentials, or omit both to use the host's default credential chain

PUBLIC_BASE_URL must point at the publicly readable origin for artifacts: the storage domain in a default install, or your CDN domain if fronted.

On the default Compose stack, S3_ENDPOINT, S3_BUCKET, and MinIO credentials are set in docker-compose.selfhost.yml. Changing only STORAGE_ADAPTER in .env.selfhost does not retarget the server at AWS S3 or R2.

Google Cloud Storage​

Set STORAGE_ADAPTER=gcs with:

  • GCS_PUBLIC_BUCKET: artifacts clients download
  • GCS_INTERNAL_BUCKET: staged uploads (_internal/*); must be a different bucket

GCS is not part of the default Compose installer. Use it when you run Patch on GCP infrastructure instead of the bundled MinIO container. The runtime uses Application Default Credentials from the host environment.

Delivery adapter​

Controls how storage keys become client-facing download URLs and whether the server purges an edge cache after each release.

ValueTypical use
base-urlDefault. URLs are PUBLIC_BASE_URL + storage key. No CDN integration.
cloudflareStorage domain is proxied through Cloudflare; server calls the Cache Purge API after releases

With base-url, clients hit your storage domain directly (Caddy → MinIO in the default stack).

With cloudflare, manifest URLs still use PUBLIC_BASE_URL, which should be the Cloudflare-fronted storage domain, and Patch purges cached manifest URLs after releases, promotions, rollbacks, and related deployment changes. Setup: Cloudflare setup.

Purge is best-effort: a failed purge does not roll back a release, but you may see stale bundles at the edge until the cache expires.

When adapters matter​

You usually need to think about adapters when:

  • Download volume or geographic reach outgrows a single origin: add Cloudflare (Cloudflare setup)
  • You want managed object storage instead of bundled MinIO: customize the deployment so the server reaches AWS S3, R2, or GCS (the Compose installer keeps MinIO wired in)

You usually do not need to change adapters when:

  • You are evaluating Patch or running a single Docker host
  • You publish through cmpatch and the dashboard on the default installer layout

The server accepts MODE=api and MODE=worker, but the self-host Compose topology is MODE=all only. Caddy does not expose /worker/* publicly. Split API/worker is not a turnkey self-host option.

Client config stays the same​

Adapter changes are server-side. Apps still need two URLs:

App configPoints at
CodemagicPatchApiUrlAPI / control plane (metrics, auth)
CodemagicPatchDownloadBaseUrlPUBLIC_BASE_URL, storage domain or CDN-fronted equivalent

If you add a CDN, CodemagicPatchDownloadBaseUrl should match the CDN-facing base URL clients actually fetch from, not the raw MinIO origin.