Cloud Storage

Customer-owned, S3-compatible object storage for public uploaded files. Permissioned/private files always stay on local disk.

Overview

Each Joinery instance can be configured with one S3-compatible bucket (AWS S3, Backblaze B2, Cloudflare R2, Wasabi, DigitalOcean Spaces, MinIO, etc.). Public uploads (photos, gallery images, blog images) are asynchronously moved to that bucket; the customer carries the storage cost rather than the platform.

Uploads themselves are unchanged — they always land locally first. A scheduled task pushes public files to the bucket on the next cron tick. Private files are never put in the bucket.

Architecture

Upload arrives → UploadHandler → File row created (fil_storage_driver='local')
                                                     │
                                                     ▼
                                    Cron tick (every 15 min)
                                                     │
                                                     ▼
                            CloudStorageSync iterates eligible rows:
                              - public per is_public()
                              - fil_storage_driver = 'local'
                              - fil_sync_failed_count < 5
                                                     │
                            Push original + variants concurrently
                            Re-check is_public()
                              ├── still public → flip flag to 'cloud',
                              │                  delete local copies
                              └── went private → undo bucket pushes,
                                                 leave row at 'local'

The per-row fil_storage_driver flag is the source of truth. A misconfigured global setting cannot strand existing files because each row independently records where its bytes live.

Bucket Layout

<site_template>/<filename>            ← original
<site_template>/<size>/<filename>     ← variants (thumb, avatar, ...)

The <site_template> prefix is derived automatically from the site_template setting (e.g. joinerytest). Multiple Joinery instances can safely share one bucket — each gets its own prefix without any configuration. The prefix is intentionally not configurable: changing it would orphan every existing object in the bucket.

The bucket must be publicly readable. The customer applies that policy at bucket creation; the platform never tries to set it.

Settings

All configured via the admin page at /admin/admin_cloud_storage. Stored in stg_settings:

Auto-Derivations

• Path-style vs virtual-hosted addressing. Derived from the endpoint

• Public base URL when empty:

Admin UI

/admin/admin_cloud_storage has a single primary Save button that:

1. Runs a three-step Test Connection diagnostic against the pasted

1. On pass, saves settings, sets cloud_storage_enabled = true,

1. On fail, displays per-step diagnostic output with remediation; nothing

When enabled, two additional buttons appear:

• Pause Cloud Storage — disables the feature and deactivates the

• Disable and Pull Files Back to Local — same as Pause, plus

The page also renders a live status block at the top: cron heartbeat, driver ping, sync task status, file counts, and any "stuck" rows (failed 5+ times). Stuck rows have a per-row "Retry" button.

Test Connection Steps

1. Reach + authenticate. A HeadBucket call. Pass means DNS, TCP/TLS,

1. Write + read public. PUT a scratch probe at

1. Delete. DELETE the scratch probe. On 403, a yellow note flags

Egress

The feature exists to save customers storage cost, but raw-bucket egress can dwarf storage savings (AWS S3 egress is ~4× the per-GB storage cost). Use a CDN.

The recommended pattern: B2 + Cloudflare via the Bandwidth Alliance — free egress between B2 and Cloudflare. Cheapest realistic option for most customers.

Other good options:

• Cloudflare R2 — free egress built in, S3-compatible API.
• Bunny.net in front of any bucket — cheap egress.

• Inline yellow banner as the admin types the public URL or endpoint

• Pre-enable confirm dialog if the admin clicks Save with a raw

• Test Connection step 2 also inspects response headers and reports

Migration

Forward (local → bucket)

The CloudStorageSync task is the forward migration. When cloud storage is first enabled, the batch query naturally selects every public local file and the task drains them across cron ticks until the queue is empty. There is no separate migration task.

Migration starts on the next regular cron tick (within 15 minutes). To start sooner, click "Run Now" on the Scheduled Tasks admin page.

The task is bounded per run (50 rows or 60 seconds, whichever first). Failures increment fil_sync_failed_count; after 5 consecutive failures a row is excluded from the batch query and surfaces in the admin UI as "stuck." The "Retry" button resets the counter and re-queues the row.

Reverse (bucket → local)

CloudStorageReverseSync is activated only by the "Disable and Pull Files Back to Local" button. Per-row, three phases:

1. Pull bytes to a temp dir.
2. Place files into the correct local dir (re-evaluated against

1. Best-effort bucket delete. Failures here are logged with

Self-deactivates when no more 'cloud' rows remain.

Permission Changes (cross-storage)

When a file's is_public() flips, the file moves between local and bucket.

Public → private (cloud → local)

Synchronous from the admin's request, three explicit phases:

1. Pull all bytes to a temp dir. Failure: drop temps, leave bucket

1. Delete from bucket with brief retries. Any failure: re-PUT

1. Copy temps to restricted local dir, commit DB row. Failure:

Invariants: bucket is authoritative until DB commit; temps live until DB commit so they remain rollback material.

Peak local disk during a flip ≈ 2× total file size (temp + restricted-dir copy, briefly during phase 3).

Private → public (local → bucket)

The synchronous path doesn't push to the bucket. The row stays at 'local'; the next sync task tick picks it up. Avoids blocking the user's request on bucket I/O.

URL Generation

File::get_url($size_key, $format) dispatches on the row's flag:

• fil_storage_driver = 'local' — existing /uploads/... URL,

• fil_storage_driver = 'cloud' — driver->url(<remote_key>), the

Backwards-compatible /uploads/* redirect

Pre-migration /uploads/<filename> URLs (in sent emails, search index caches, RSS feeds, embedded HTML) keep working: serve.php's /uploads/* route checks fil_storage_driver and 302-redirects cloud rows to the bucket URL with Cache-Control: public, max-age=86400. After the first hit the browser caches the redirect; subsequent hits skip PHP entirely.

Bucket Policy / Setup

Backblaze B2

1. Create a bucket; set its type to Public.
2. Create an application key scoped to that bucket with read+write+delete.
3. The endpoint is s3.<region>.backblazeb2.com (region matches the

1. Front the bucket with Cloudflare for free egress via the

AWS S3

1. Create a bucket; disable "Block all public access" for the

1. Apply a bucket policy granting public read on the prefix:

1. Create an IAM user with a policy granting read/write/delete on the

1. Endpoint: s3.<region>.amazonaws.com. Region matches the bucket

1. Strongly recommended: front the bucket with CloudFront or another

Cloudflare R2

1. Create an R2 bucket.
2. In the bucket's settings, attach a public custom domain or enable

1. Endpoint: <account-id>.r2.cloudflarestorage.com.
2. Region: auto.
3. cloud_storage_public_base_url should be the public custom domain

Provider Compatibility

Failure Modes

File-by-File Architecture

Out of Scope (v1)

• Per-tenant / per-user buckets within a single Joinery instance.
• Bucket-level encryption configured via the admin UI (customer

• Resize-on-demand (variants still generated upfront).
• Automatic CDN setup (customer responsibility, documented above).
• Egress monitoring or alerts based on actual bytes served.
• Storing private/permissioned files in the bucket. Private files stay