Choose a mode
See
examples/platform-modes in the Towbar repository for a validated example of every mode.
Source builders
Source builders accept a repository-relative context, build and start commands, cache settings, architecture, timeout, build arguments, and CPU/memory limits. Paths cannot escape the context through.. or symbolic links. Tool and builder images must be pinned by digest.
Dockerfile builds pass protected build values through BuildKit secret mounts. Static build commands receive protected values only in their short-lived build environment. Railpack, Nixpacks, and Buildpacks currently reject protected build secrets because forwarding them through their environment or cache could retain them in image layers. Use a Dockerfile when a build requires credentials.
Cancellation stops the active remote command and cleanup removes staged source and unpromoted images. A build cache is scoped to the workload unless the manifest explicitly declares another authorized scope.
Prebuilt images
Use a named registry integration for a private image. Towbar contacts the Registry V2 API during admission, follows supported bearer challenges, resolves the tag to a digest, and stores the original reference and immutable digest.latest is rejected. A different digest at execution time fails the deployment rather than silently deploying changed content.
Private registry endpoints require HTTPS. Private-network access is disabled unless it is enabled on the integration. The workload platform and target server architecture must agree.
Build servers
Setdefaults.buildServer at the manifest root to use another registered server for every build in that repository environment. Because each connected environment reads its own immutable manifest revision, a branch can declare a different environment default. An app-level buildServer overrides the default; set it to null to build that app on its runtime server. The selected server must belong to the team, have trusted SSH credentials, be prepared, and support the requested architecture. direct transfer streams the verified image archive to the runtime server. registry transfer uses a named registry integration and verifies the pushed and pulled digest.
Build-server capacity and concurrency are reserved independently from runtime operations. Towbar does not fall back to the runtime server unless allowRuntimeFallback: true is explicitly set. A missing or unavailable build server otherwise fails closed.
Build servers apply to individual app build modes. Compose builds run on the selected runtime server because Compose resolves and builds the service graph as one project; buildServer is rejected on Compose workloads instead of being accepted and ignored.
Build caches are isolated by the configured scope. Towbar refreshes the scope marker after a successful use, removes the scope immediately when caching is disabled, and reclaims scopes that have been inactive for 30 days. Dockerfile and static cache images and Buildpacks cache volumes carry managed labels so ordinary release cleanup does not remove the active cache.
Rolling and recreate strategies
Eligible stateless apps use a health-gated rolling strategy. Configure replicas, surge, maximum unavailability, startup deadline, minimum healthy time, failure threshold, drain time, and termination time. Admission checks declared CPU and memory headroom for the surge before replacing a replica. A candidate must remain healthy for the configured interval; repeated failed checks abort promotion and retain the previous release. Userecreate with a reason for stateful single-writer volumes, fixed host ports, or another workload that cannot run old and new instances together. App rollback selects an earlier release; it does not reverse a database migration or restore persistent data.
Compose projects
Declare a Compose workload in.towbar/compose. Towbar runs the installed Docker Compose v2 plugin to parse and validate the project. Compose files may use repository-relative overrides, profiles, service dependencies, health checks, repository builds, explicit non-latest images, named volumes, and manifest-declared public service policies.
Towbar validates every Compose document before Docker Compose opens it, including recursively referenced local includes and extends files. References must stay inside the immutable repository checkout; remote includes, include project-directory overrides, external or explicitly named Docker resources, privileged containers, external namespaces, Docker socket or host bind mounts, devices, fixed or publicly bound host ports, and unsupported routing combinations are rejected. It supplies a generated environment file for resolved runtime values and removes the transfer copy after execution. Partial updates retain a stable previous project definition so recovery can bring the previous stack back without deleting project volumes. Compose projects use recreate or maintenance replacement; rolling Compose replacement is rejected rather than emulated.