Skip to main content

​
Goal

Configure and deploy Assets through the platform release process while preserving stored media and existing delivery.

​
Prerequisites

  • The coordinated platform release owner, exact source/artifact identities and access to the existing operator runbooks.
  • A complete private environment, ready storage/scanner dependencies and the Assets implementation.
  • Owned or licensed fixtures; isolated containers and production build artifacts rather than an assumed staging server.

​
Workflow

1
Validate the environment and Compose projection, preserving storage and signing identity.
2
Build matching API/worker/frontend/player/gallery artifacts and review the full pending migration sequence.
3
Run isolated tests, media/security acceptance and the real browser/device matrix.
4
Use the existing coordinated release process; initially keep new admission off and verify deployed dependencies.
5
Enable the configured capabilities, monitor persisted job/delivery/cleanup state, and retain rollback evidence.

​
Preflight and existing release boundaries

Assets shares API/frontend images, the worker image, database migrations and blue/green worker fences with other platform products. There is no independent Assets-only hot swap. Preserve concurrent release ownership and use a coordinated reviewed source snapshot. Relevant additive migrations include native-video/storage changes 411–413, governance/models/galleries/search 417–420, product rendering 423 and the automatic Assets Free plan in 430. These are not an isolated list to apply: inspect every pending migration in order, including intervening or later non-Assets migrations. Back up and verify restore before the normal migration step. Do not copy only selected Assets SQL, mark migrations applied by hand, change a release fence, or replace an individual worker image to bypass the shared release process. Preparation does not authorize deployment or package/image publication.

​
Local checks and immutable worker probe

assets-check never deploys. The test mode needs installed repository dependencies. The worker probe requires a locally available immutable image, uses no network and checks the worker executable, FFmpeg/ffprobe, a short MP4/HLS encode and OCR/PDF tools under the configured limits. Check scanner and storage connectivity separately through the application.

​
Build frontend with the actual shared packages

The production frontend Dockerfile needs the assets_player and assets_gallery named contexts. Both existing deployment callers pass them; a standalone build must do the same. Do not omit these contexts or substitute a separately implemented preview. Environment files are excluded from frontend build inputs.

​
Check worker and origin services

  • Verify the exact deployable API/worker images, real app boot, shared release fence and dedicated Assets queue routing. One native encode per Assets worker process is the default; keep capacity for other asset jobs.
  • Verify actual FFmpeg/ffprobe versions inside the final worker image, ClamAV service health and signature freshness, writable bounded scratch, storage permissions and required replicas.
  • Exercise stackshift-assets, stackshift-assets-video and stackshift-assets-model jobs with owned fixtures; rendering and native model validation use different execution paths despite sharing a model job kind.
  • Test corruption, rotation, silence, variable frame rate, multiple audio tracks, small inputs and resource exhaustion. Test partial rendition failure, cancellation, lease loss, replacement races, billing idempotency and cleanup.
  • Verify private playlists, every child segment, MP4, poster and caption through both edge and direct-origin policy. Test cross-tenant denial, revocation, HEAD/ranges, CORS and cache transitions.

​
Cloudflare routes, permissions and credential logs

Configure the actual Cloudflare zone, account and existing Assets Worker service. The API token needs the permissions used by Assets zone, cache and custom-domain operations. Use the Caddy formatter that removes playback/token/sig query credentials and request headers from API/CDN logs. Disable automatic Worker invocation logs that record full request URLs. Apply equivalent credential redaction in upstream proxies, Tail Workers, Logpush and error reporting. Keep delivery signing and edge-to-origin secrets consistent between API and Worker.

​
Configure product rendering

  • Configure the Cloudinary account credentials in the API and Assets worker environment. Keep those credentials server-side.
  • The configured credentials enable proof, poster, spin and turntable without extra provider budgets or launch allowlists. Preserve the customer’s purchased rendering allowance.
  • Use a current, scanned GLB with a ready model package. Inspect rendering.enabled, reason and qualified_outputs through the models endpoint.
  • Check the customer workflow: estimate, explicitly request outputs, inspect status, review the finished set, create a publication and publish it.
  • Monitor failed sets and provider cleanup. Retain provider credentials until outstanding cleanup has completed.

​
Rollback without breaking existing delivery

For an operator-requested rollback, stop new native-video admission with ASSETS_NATIVE_VIDEO_ADMISSION=false and stop new rendering submissions at the API while retaining worker cleanup. Apply configuration changes through the coordinated release procedure; editing a file does not change an already running container. Retain signing/origin secrets, active/session-referenced packages, published output records, tracked storage and additive schema. Preserve provider credentials until outstanding cleanup is reconciled. Previously published StackShift outputs should not depend on Cloudinary availability. Roll back images through the existing release/fence controls after schema compatibility checks. Do not execute down migrations on populated render/video data as an emergency shortcut, reset reservation ledgers or bulk-delete provider/object-store data.

​
Expected result

API and Assets workers receive the intended configuration, deployment checks cover processing and delivery, and rollback can stop new jobs while retaining existing packages.

​
Common failures

  • Omitting the player/gallery Docker build contexts.
  • Changing signing secrets or storage identity unintentionally.
  • Removing provider credentials before cleanup completes.

Operator reference: Assets environment

Every Assets environment variable, its preparation default, secret boundary, runtime destination, and activation prerequisite.

Product rendering: images, spins and turntables

Use model-preview controls, estimate rendering units, request proofs or final media, and publish approved immutable outputs.

Upload, validate and publish 3D models

Prepare supported GLB and supplied USDZ files, inspect validation reports, add posters, review the model and launch authorized device AR.

Native video processing and secure playback

Version-pinned video packages, scan and review gates, replacement behavior, playback sessions, API routes, and failure recovery.