> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Operator reference: Assets deployment and rollback
> Configure Assets services, build images, run deployment checks, and roll back processing admission without interrupting existing delivery.
## 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
Validate the environment and Compose projection, preserving storage and signing identity.
Build matching API/worker/frontend/player/gallery artifacts and review the full pending migration sequence.
Run isolated tests, media/security acceptance and the real browser/device matrix.
Use the existing coordinated release process; initially keep new admission off and verify deployed dependencies.
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.
```bash theme={null}
./deploy.sh assets-check --env-file /private/platform.env
./deploy.sh assets-check --tests
# Replace the image reference with an already acquired image digest:
./deploy.sh assets-check --worker-image \
registry.example/stackshift-worker@sha256:ACTUAL_64_CHARACTER_DIGEST
```
## 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.
```bash theme={null}
docker buildx build --platform linux/amd64 \
--build-context assets_player=./packages/assets-player \
--build-context assets_gallery=./packages/assets-gallery \
--build-arg VITE_API_BASE_URL=https://api.stackshift.cloud \
--tag stackshift-assets-frontend:local --load \
-f stackshift_frontend/Dockerfile stackshift_frontend
```
## 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.
## Related guides
Every Assets environment variable, its preparation default, secret boundary, runtime destination, and activation prerequisite.
Use model-preview controls, estimate rendering units, request proofs or final media, and publish approved immutable outputs.
Prepare supported GLB and supplied USDZ files, inspect validation reports, add posters, review the model and launch authorized device AR.
Version-pinned video packages, scan and review gates, replacement behavior, playback sessions, API routes, and failure recovery.