Skip to main content
The GCP Cloud Run package runs HyperFrames’ distributed render primitives on Google Cloud. It ships a Cloud Run HTTP service, a Node client SDK, and a Terraform module for provisioning the bucket, service, workflow, and service accounts.

​
When to Use

Use @hyperframes/gcp-cloud-run when you need to:
  • Render large compositions on Google Cloud infrastructure
  • Orchestrate plan, renderChunk, and assemble through Cloud Workflows
  • Store project archives, chunk outputs, and final videos in GCS
  • Deploy the renderer as a Cloud Run service with a pinned Chrome runtime
  • Drive renders from CI, a backend service, or custom internal tooling
Use a different package if you want to:
  • Render locally or inside a single Node process - use the CLI or producer
  • Run the same distributed model on AWS - use aws-lambda
  • Build or edit composition HTML - use studio, sdk, or core
Cloud Run uses a container image, so it avoids Lambda ZIP-size pressure and can install the same pinned chrome-headless-shell runtime used by the standard renderer.

​
Package Exports

The published package also includes terraform/ and a Dockerfile for deployment.

​
Architecture

Cloud Workflows invokes one Cloud Run service with different Action values:
1

Plan

Downloads the project archive from GCS, runs the producer planner, and uploads the plan directory.
2

Render chunks

Cloud Workflows runs parallel renderChunk calls against the Cloud Run service. Each request renders one chunk and uploads it to GCS.
3

Assemble

Downloads all chunks and audio assets, assembles the deliverable, and uploads the final file.
The service is intentionally close to the AWS Lambda adapter: thin cloud transport around the same @hyperframes/producer/distributed primitives.

​
Deploying

Build and push the container, then apply the Terraform module:
Terraform outputs the bucket name, service URL, workflow name, and region needed by the SDK.

​
Using the SDK

Plan v2 is the default because workers fetch manifest-selected content-addressed artifacts. The SDK sends explicit v2 when planProtocol is omitted. Deprecated v1 compatibility remains available by passing planProtocol: "v1".
For an existing installation, pause new renders and drain active workflow executions. Redeploy the Cloud Run image and Cloud Workflows definition from the same package version before upgrading the application SDK. Older workflows may default omission to v1 or lack v2 support.
Pass projectDir for one-shot uploads, or call deploySite() separately and reuse the returned site handle across many renders.

GCP Cloud Run Deployment

End-to-end deployment details and smoke-test notes.

@hyperframes/producer

The distributed primitives that the Cloud Run service executes.