Flowmaker SDK [beta]Docs
search
GitHub

Docker Worker Integration and Peer-Dependency Caching

This page describes how @cdn-cache dependencies are prepared in worker Docker images.

Node worker template: dedicated CDN helper stage

Node worker Dockerfiles include a first stage that collects frontend peer dependencies:

FROM ghcr.io/industream/cdn-helper:1.0.9 AS cdn-helper
COPY frontend/package.json /tmp/package.json
RUN /cdn/collect-deps.sh /tmp/package.json

This prepares runtime CDN metadata/artifacts from frontend/package.json before backend/frontend build stages are assembled.

[NOTE!lightbulb/WHY THIS EXISTS] The helper stage lets the final runtime resolve @cdn-cache imports consistently, aligned with the exact peer dependency versions declared by the frontend.

Cache behavior in Docker builds

  • COPY frontend/package.json defines the cache key for the collect step.
  • If frontend/package.json is unchanged, Docker can reuse the collect-deps layer.
  • If any peer dependency version changes, the layer invalidates and dependencies are recollected.

[WARNING!shield/CACHE INVALIDATION IS CORRECT] Cache invalidation on version changes is expected and necessary for reproducible runtime behavior.

Relationship with frontend build stage

The frontend build stage still runs pnpm install and pnpm run build using the same frontend/package.json.

[NOTE!lightbulb/PRACTICAL GUIDELINE] Keep peer dependency declarations explicit and pinned (x.y.z) to match @cdn-cache/package@x.y.z imports used in the frontend source.

Runtime handoff in final image

Node template final stage copies helper runtime assets:

COPY --from=cdn-helper /cdn-runtime /cdn-runtime
ENTRYPOINT ["/cdn-runtime/docker-entrypoint.sh"]

This is the runtime integration point for CDN substitution/serving behavior in the worker container.

Template differences by worker runtime

  • Node template: includes cdn-helper + /cdn-runtime entrypoint integration.
  • Python/.NET templates: currently build frontend bundles but do not include the cdn-helper stage in their default Docker templates.

Reference

  • sdk/worker/repo-management/templates/node/Dockerfile
  • sdk/worker/repo-management/templates/python/Dockerfile
  • sdk/worker/repo-management/templates/dotnet/Dockerfile