Rampway Deploy

Rampway is a JavaScript-native release-directory deployment tool: the useful parts of Capistrano, built for Node/Expo/Velocious projects and designed to hand runtime changes to Rollbridge.

Package: rampway
CLI: rampway
Config: rampway.config.mjs

Current MVP

This initial scaffold includes:

• ESM config loading and validation
• deterministic deploy plans
• local release-directory deploys for tests/dogfooding
• linked file/dir checks and symlink creation
• deploy lock acquisition/release
• release metadata (REVISION, TRESTLE_RELEASE.json)
• atomic current symlink publishing
• safe cleanup
• revision-fenced, idempotent post-publish cleanup recovery
• rollback to previous or selected release
• guarded publication recovery for an already-committed exact release
• JSONL deploy reports at shared/log/rampway-deployments.jsonl
• secret redaction helpers
• basic runtime adapter interface with none and Rollbridge validate/deploy/status/logs/recover helpers
• optional Rampway-owned authenticated Velocious deployment API at rampway/velocious

SSH transport command execution supports both local-copy and remote-git deployments. remote-git prepares each release checkout on the target host, so the target needs git and access to the configured repository.

Ordinary SSH projects need only deployment facts:

transport: {
  type: "ssh"
},
hosts: [{host: "server.example", user: "deploy"}]

Rampway enforces strict host-key checking with the standard OpenSSH known-hosts locations and selects deploy.key beside the config before readable standard user identities for the direct deployment-host connection. A usable inherited agent remains available for onward authentication, or as the direct fallback when no identity file exists; otherwise Rampway owns a private agent for the command and loads the discovered identities. SSH-form remote-git repositories enable agent forwarding by default. Rampway pins the resolved socket with IdentityAgent; optional standard identities rejected by ssh-add are skipped after the selected deploy identity loads. Local control-plane branch resolution uses the same strict known-host and agent profile, while pinned-revision HTTP deploys do not require unused local SSH credentials. See the config reference for deterministic identity, known-host, forwarding, and SSH-option overrides.

Guard a recovery deploy against an unexpectedly changed active release with:

rampway production deploy CANDIDATE_FULL_SHA --expected-active-revision ACTIVE_FULL_SHA

Both values must be full 40-character hexadecimal commit SHAs. The existing before_deploy and before_lock hooks still run before lock acquisition and remain outside the guard's protection. After Rampway acquires the normal deploy lock, its first locked operation strictly resolves current and reads that release's REVISION. A missing, unsafe, malformed, or mismatched current release fails before after_lock and all candidate/source, task, migration, backfill, runtime, and publication work. This option has no bootstrap semantics, and --force cannot bypass it. Deploys without the option retain the ordinary lifecycle.

Full config reference: docs/config-reference.md Migrating from Capistrano: docs/migration-from-capistrano.md

Docker development environment

Rampway's canonical development environment is one persistent dev service built from the root Dockerfile: digest-pinned Ubuntu 26.04 LTS, exact signed/checksummed NodeSource Node 24, the universal coding/debugging baseline, and the current OpenCode, Codex, Claude Code, and official Kimi Code CLIs. The image is source-independent and installs no project dependencies or Threadwire.

Copy the portable environment template, prepare mount-target directories, start the service, and install locked dependencies inside it:

cp .env.example .env
scripts/prepare-dev-home.sh
docker compose up --build --detach dev
scripts/docker-run.sh npm ci

The complete dedicated development home is mounted at /home/dev; GitHub CLI configuration mounts read-only, and Hermes' shared provider runtime supplies Codex, OpenCode, and Kimi authorization through UID/GID-1000 bootstrap links. scripts/docker-run.sh executes project commands through the already-running service. Use a distinct COMPOSE_PROJECT_NAME and DEV_HOME_PATH for each concurrent instance.

Setup, credential boundaries, isolation, static checks, and Docker-capable coordinator validation are documented in docs/docker-development-environment.md.

Commands

rampway init
rampway production validate
rampway production plan
rampway production plan <revision>
rampway production plan --json
rampway production deploy
rampway production deploy <revision>
rampway production deploy --transport=auto
rampway production deploy --transport=http
rampway production deploy --transport=ssh
rampway production status
rampway production releases
rampway production releases --json
rampway production task cache:warm
rampway production task cache:warm --json
rampway production tasks
rampway production tasks --json
rampway production rollback
rampway production resume-publication <exact-release-id>
rampway production cleanup-releases --expected-active-revision <active-full-sha>
rampway production cleanup-releases --expected-active-revision <active-full-sha> --dry-run
rampway production doctor
rampway production doctor --json

# Runtime maintenance for the current release
rampway production runtime-validate
rampway production runtime-status
rampway production runtime-logs
rampway production runtime-recover --yes
rampway production runtime-recover-generation-transition <failed-release-id> --yes

# Local foreground host-restart entrypoint for the last accepted release
rampway production runtime-boot --config /absolute/path/rampway.config.mjs

The older rollbridge-validate, rollbridge-status, rollbridge-logs, and rollbridge-recover names remain aliases for Rollbridge stages.

Use exact failed-generation recovery when a Rollbridge deploy timed out or failed before publication and retained its candidate transition fence. Recovery supports stages without an explicit runtime.config, and later successful Rollbridge deploys refresh live retained release pins before cleanup.

Post-publish cleanup recovery

Publication and healthy runtime activation are the deploy success boundary. If only Rampway's built-in release-retention cleanup fails after that boundary, the deploy returns success as deployed and active with cleanup pending, persists a bounded cleanupFailure, and prints the exact revision-fenced recovery command:

rampway production cleanup-releases --expected-active-revision ACTIVE_FULL_SHA

The recovery command takes the normal deploy lock and verifies the exact persisted revision from the current release while holding the lock. Its fence also supports local-copy branch labels and full 64-character Git revisions; canonical 40- and 64-character hexadecimal revisions compare case-insensitively, while other tokens compare exactly. A direct CLI deploy preserves its resolved --config path in the generated command. Rampway then inventories live release/runtime state, and removes only Rampway-managed releases that exceed keepReleases and have no current, active-runtime, draining-runtime, or durable runtime-pin protection. It replans before deletion and verifies by replanning afterward. Ambiguous remote deletion or listing failures cause live-state readback; Rampway never infers whether a remote delete ran from exit status alone. Retries are idempotent. --dry-run holds the same fence and reports the plan but does not delete releases or append a cleanup report.

Cleanup recovery never deploys code, hands off or restarts a runtime, changes current, or runs application hooks. Failures from before_cleanup, after_cleanup, report persistence, and lock release remain ordinary nonzero deploy failures rather than cleanup-pending successes.

Deploy transports

Deploys run over one of three transports selected with --transport:

• http — run the deploy through the authenticated Velocious control plane (requires stage.http). Fails if the stage has no control-plane config.
• ssh — run directly over the stage's SSH (or local) transport, bypassing the control plane.
• auto (default) — use the control plane when the stage configures stage.http, and fall back to the direct transport only when the control plane is unreachable or the project/stage is not deployed there. Never falls back on authentication or validation errors, or once a run has been admitted.

Dry runs always use the direct transport and print a plan, regardless of --transport.

Readable deploy output and automation

A normal deploy reports timed lifecycle progress and a concise result. Full shell commands and redacted child stdout/stderr are written to the per-deploy log instead of flooding the terminal:

$ rampway production deploy
Logging deploy output to /srv/app/log/deploys/20260904123000-production.log
Deploying app/production revision 4f31c21 as release 20260904123000
→ Preparing deploy directories
✓ Preparing deploy directories (0.1s)
→ Task install
✓ Task install (8.4s)
✔ Deployed app/production revision 4f31c21 as release 20260904123000 in 12.7s
  Deploy log: /srv/app/log/deploys/20260904123000-production.log

Set deployLog: false explicitly to disable the persistent transcript. Human deploys then retain the previous fallback of streaming redacted child output to stderr so diagnostics are not discarded.

Use --json when another program consumes the result. It suppresses lifecycle and child output and writes exactly one final JSON report, including for a failed deploy:

rampway production deploy --json > deploy-report.json

For local development without installing the package globally:

node src/cli.js init
node src/cli.js local validate --config examples/local/rampway.config.mjs
node src/cli.js local plan --config examples/local/rampway.config.mjs
node src/cli.js local deploy --config examples/local/rampway.config.mjs

# Monorepo example with backend + frontend stages
node src/cli.js local validate --config examples/monorepo/rampway.config.mjs
node src/cli.js local plan --config examples/monorepo/rampway.config.mjs

Config example

Reusable Node package install helpers can be imported from rampway/tasks when writing rampway.config.mjs:

import {npmInstall, pnpmInstall, checkExpoWebArtifacts, velociousMigrate, onlyIfChanged} from "rampway/tasks"

// rampway.config.mjs
export default {
  application: "routergeist",
  stages: {
    production: {
      repo: "[email protected]:kaspernj/routergeist.git",
      branch: "master",
      deployTo: "/home/dev/routergeist",
      strategy: "remote-git",
      transport: {type: "ssh"},
      hosts: [{host: "server.example", user: "dev", roles: ["app", "web", "db"]}],
      keepReleases: 5,
      linkedFiles: [
        {path: "backend/src/config/secrets.js", required: true}
      ],
      linkedDirs: ["log", "tmp/pids", "tmp/cache", "storage"],
      tasks: {
        install: [
          npmInstall({cwd: "backend", production: true}),
          pnpmInstall({cwd: "app", production: true})
        ],
        migrate: [
          velociousMigrate({cwd: "backend", env: {NODE_ENV: "production"}})
        ],
        build: [
          "cd app && npm run web:export",
          checkExpoWebArtifacts({dir: "app/dist"}),
          {command: "npm run assets:verify", cwd: "app", env: {NODE_ENV: "production"}}
        ]
      },
      operationalTasks: {
        "cache:warm": {
          command: "npm run cache:warm",
          cwd: "backend",
          env: {NODE_ENV: "production"},
          forwardEnv: ["CACHE_WARM_CREDENTIAL"]
        }
      },
      runtime: {
        type: "rollbridge",
        command: "npx rollbridge",
        packageDir: "backend",
        config: "config/rollbridge.production.mjs",
        daemonLogPath: "/home/dev/routergeist/shared/log/rollbridge.log",
        daemonPidPath: "/home/dev/routergeist/shared/tmp/pids/rollbridge.pid",
        socketPath: "/tmp/rollbridge-routergeist.sock",
        versionPath: "/home/dev/routergeist/shared/tmp/rollbridge-version"
      }
    }
  }
}

For Rollbridge, an explicit runtime.config is resolved relative to runtime.packageDir, fingerprinted with the Rollbridge package version, runtime options, and environment values, then copied into immutable Rampway-owned material under shared/rampway/runtime/. After runtime and health succeed, Rampway atomically records only the known-good digest and secret-free activation locators in shared/rampway/state.json, indexed by release. Secret environment values participate in change detection but are never stored or logged. Keep the Rollbridge config self-contained; imported sibling files are not copied.

That stable state lets rollback and runtime maintenance target a retained release whose checkout has no Rampway helper or Rollbridge config. packageDir remains relative to the selected application release, while the stored config comes from trusted known-good material. A missing, malformed, mismatched, or config-less Rollbridge state fails rollback before runtime or current changes. The first successful Rampway deploy with an explicit config seeds this state.

For a candidate snapshot using Rollbridge 0.1.29 or newer, Rollbridge owns incompatible config, socket, package, and runtime-owner replacement inside rollbridge deploy --ensure-daemon. Rampway validates and deploys that candidate without first shutting down the incumbent, and it surfaces a failed replacement without the destructive legacy shutdown/retry fallback. When Rollbridge reports that a rejected incompatible replacement left the incumbent authoritative, Rampway also skips automatic previous-snapshot runtime restoration while keeping the deploy or rollback failed, current, accepted runtime state, and the original causal error unchanged. Candidates older than 0.1.29 retain Rampway's compatibility path, which shuts down a responsive daemon before deploying a changed runtime contract and may retry a reported legacy runtime mismatch once after known-good shutdown. The first transition from a pre-split Rollbridge owner to 0.1.29+ can still be disruptive while Rollbridge uses its documented, narrowly authorized one-time pre-split bridge; Rampway does not preempt that transaction or discard its guardian-owned process state.

After a configured Rollbridge handoff and all required health checks succeed, Rampway also atomically writes shared/rampway/runtime-boot.json. This versioned, integrity-protected record contains only application/stage identity, the exact retained release and revision, the immutable config path and digest, the secret-free full runtime contract digest, and its acceptance time. It contains no runtime options, environment, commands, credentials, or output. runtime-boot is local-only and verifies that record, the retained release metadata, REVISION, current, the identical active and retained runtime snapshot, its rollback compatibility, and immutable config bytes before spawning Rollbridge 0.1.17 or newer in the foreground using:

rollbridge daemon --config <absolute-config> --release-path <absolute-release> --release-id <id> --revision <revision>

The command never deploys or selects a fallback release. Missing, corrupt, stale, mismatched, or config-less state fails closed. A service manager should supervise rampway; Rampway does not supervise Rollbridge. A valid schema-1 boot record is upgraded atomically after its matching runtime snapshot, material, and rollback compatibility have been verified. An exact lock-bound external-owner handoff keeps its schema-1 record and attestation unchanged; the next unlocked restart performs the migration.

For a persistent external foreground owner, opt in with runtime.externalOwner: {type: "foreground"} (Rollbridge 0.1.38+). Optional handoffTimeoutMs and pollIntervalMs positive integers bound the transition; handoffTimeoutMs is one deadline for the authenticated retire-owner socket round trip and the subsequent replacement polling after initial owner identity verification. This mode requires an explicit runtime.config so Rampway can persist stable foreground boot material before any ownership transition. Each deploy or rollback must establish the newly accepted boot attestation. If the current foreground owner already reports that exact identity, it remains untouched. An unreadable status or a release/runtime identity mismatch fails closed without shutdown. When only the bootstrap is absent or stale, Rampway sends one authenticated retire-owner control command — attested with the accepted boot-state digest — through the configured runtime.socketPath control socket. Retirement quiesces the old owner and releases its proxy/control listeners promptly without waiting for long-draining workers, so a serial outer supervisor can start the ordinary attested runtime-boot replacement while the retired owner finishes draining. A stalled, truncated, malformed, or non-success retirement response fails the handoff deterministically within handoffTimeoutMs, without retrying retirement or taking over the owner. Deploying over a retained external owner running Rollbridge older than 0.1.21 fails closed before any shutdown or deploy, because those versions cannot be retired without interrupting service while workers drain; stage the migration through an intermediate 0.1.21+ release with runtime.externalOwner disabled in an explicitly planned maintenance restart, scheduled only after accepted long-running workers have drained, then upgrade to Rollbridge 0.1.38+ before re-enabling it. Rampway accepts only the exact release, runtime, and boot-digest attestation; timeout or replacement failure preserves the accepted boot state and handoff request for supervisor retry. Rampway never signals a status-reported PID and does not invoke the service manager.

Required retained-runtime boundary

A release-scoped background-jobs generation comprises that release's jobs-main and worker pool. The complete candidate generation starts before activation. Deployment success is reached when the candidate release is activated and healthy; the previous jobs-main and workers then retire as one generation and drain asynchronously on their old release code and endpoint. External-owner handoff must return without waiting for that generation, its jobs, HTTP/WebSocket connections, or other retained services to exit. Those drains may continue after the deploy command returns and deploy lock is released, and later deploys must not serialize behind them.

Rampway owns the activation transaction, lock, accepted runtime metadata, release-reference pins, and cleanup enforcement. Rollbridge owns durable supervision of retained processes, including multiple concurrently draining generations and recovery after an owner or host restart. Rollbridge must report every referenced release directory, and Rampway must pin it against keepReleases cleanup until that generation has fully retired. HTTP/ WebSocket drain completion or timeout does not end a jobs-generation reference.

During external-owner handoff, Rampway persists Rollbridge's complete referenced- release set before cleanup while it still holds the deploy lock. Later deploys query the durable supervisor again, so a release remains pinned across deploys until Rollbridge no longer reports it.

When one project root has multiple independently deployed runtime owners, set a path-safe stage-level namespace on every participating stage. For example, namespace: "web" and namespace: "worker" under the same deployTo use independent releases/<namespace>, current/<namespace>, shared content, deploy locks, known-good runtime state and material, runtime boot state, owner handoff requests, and reports. Each outer owner runs runtime-boot with the config and stage for its namespace. Omitting namespace retains the legacy single-runtime paths exactly. Do not mix namespaced and unnamespaced stages in one deployTo; see the config reference.

npmInstall, pnpmInstall, yarnInstall, bunInstall, and nodePackageInstall return normal task entries with the right install command for common Node package managers. They accept cwd, env, optional, production, and lockfile options such as clean: false for npm install instead of npm ci, or frozenLockfile: false for package managers that need explicit CI lockfile opt-outs (--no-frozen-lockfile for pnpm and --no-immutable for Yarn). Yarn production installs are intentionally not guessed; use a custom task command when that project needs a specific Yarn workspace/plugin flow.

checkExpoWebArtifacts returns a task entry that fails if the Expo web build directory does not contain an index.html. It accepts dir (default "dist"), cwd, and optional.

velociousMigrate returns a task entry that runs npx velocious db:migrate. It accepts command (override), cwd, env, and optional.

onlyIfChanged(paths, task) wraps a task entry so it is skipped when none of the given relative paths have changed since the previous deploy. On the first deploy (no previous release), all tasks run regardless.

Task entries can be strings or objects.

• command — required shell command to run.
• cwd — optional release-relative working directory.
• env — optional environment variables passed to the command.
• optional — when true, the deploy records the task failure and continues.

Task groups run in config order. Required task failures stop the deploy before publish. If a candidate runtime handoff starts and then fails before publish, Rampway reactivates and health-checks the previous release using that release's known-good snapshot. Deploy failures include whether current changed and recovery hints for the affected stage, such as rerunning a before-publish failure, inspecting a newly created failed release directory, or inspecting rampway status, rampway releases, and rampway rollback after a failure that happened after publish. Existing release-id collisions do not suggest deleting the release directory.

Rollback runs under the same exclusive lock as deploy but never runs deploy task groups, migrations, or candidate-local Rampway helpers. Rampway resolves one retained release directory, activates it with the installed runtime adapter, runs the configured health checks, and only then publishes current. If target activation or health fails, Rampway reactivates and health-checks the prior release before returning the original failure. Use --to <exact-release-id> for a retained Capistrano release. Unsafe, nested, temporary, escaping, and outside-symlink targets are rejected.

Release diagnostics include safe retained legacy directories. Cleanup ownership does not: only releases carrying valid Rampway metadata for the configured application and stage count toward keepReleases or can be removed by Rampway. Cleanup excludes the current release, keeps the configured number of newest managed releases, and excludes every release referenced by the runtime owner.

Standalone operational tasks are configured separately under operationalTasks and run only when explicitly selected with rampway <stage> task <exact-name>. Rampway acquires the shared deploy lock, strictly resolves the active release, and runs every required entry against that immutable release path. forwardEnv names caller-supplied environment variables that must be present; their values are transported separately from ordinary env and redacted from output and errors. Operational tasks do not run during deploy, accept no command arguments or --force, and are not included in the plural tasks deploy-task inventory.

Callable deployments from Velocious

Velocious applications can mount the authenticated control plane exported as rampway/velocious. The HTTP API accepts only allowlisted Rampway config/stage targets, full Git commit SHAs reachable from an approved release branch, and idempotency keys. Each admitted run is handed to a detached package-owned Node worker, which reconstructs the backend Velocious context and executes Rampway's existing deploy/rollback/status lifecycle; matching live revision/fence requests coalesce onto that canonical worker, and a revision already active under the deploy-host lock returns an explicit successful no-op before release or runtime lifecycle work. Velocious remains the framework and persistence runtime. See Velocious callable deployment API for mounting, client calls, durable recovery behavior, and token rotation/revocation.

Deployment reports

Every successful deploy, rollback, or resumed publication appends one JSON object per line to shared/log/rampway-deployments.jsonl. Deploy events include:

• event: "deploy"
• application, stage, releaseId, revision, and branch
• deployedAt and durationMs
• previousRelease
• healthChecks: "passed"
• sanitized runtime status
• cleanupRemoved release IDs
• cleanupStatus: "completed" after ordinary cleanup, or "pending" when only built-in post-publish retention cleanup failed
• for pending cleanup, bounded cleanupFailure process status and confirmed partial-removal count plus the exact cleanupRecoveryCommand; these fields never contain commands, remote output, credentials, or deployment destinations
• optional warnings for non-fatal maintenance failures after runtime acceptance

Rollback events include event: "rollback", target releaseId and revision, rolledBackAt, durationMs, previousRelease, healthChecks: "passed", and a sanitized runtime result. Reports intentionally record runtime result summaries, not runtime configuration or secrets. A provisional cleanup-pin removal failure is reported as a warning and retained for later reconciliation; it does not turn an already-accepted runtime activation into a failed deploy or rollback. Rampway stores provisional pins outside accepted runtime state and clears only the pins owned by the exact runtime configuration that positively reports its live release references. Runtime changes preserve the previous owner's pins, and runtimes without reference reporting retain their unresolved pins.

Resumed-publication events use event: "resume-publication", resumedAt, the exact target and previous release identities, healthChecks: "passed", the already-committed runtime summary, and normal cleanup results.

Successful non-dry-run cleanup-releases commands append event: "cleanup-releases" reports with the revision fence, initial live plan, explicit protection reasons, confirmed removals, final remaining releases, and managed/protected/removable/removed/remaining counts. Dry runs print the same shape without appending it.

When a remote-git deploy finds the requested revision already active under the deploy lock, it appends the same bounded deploy event with idempotent: true, the active releaseId and canonical revision, and healthChecks: "unchanged" — no runtime result or health success is invented for work that did not run.

Releasing

Patch releases are cut synchronously from a clean checkout with publish access to npm:

npm run release:patch

The release script runs Rampway's lint, typecheck, and test suite before starting the shared release-patch command. That command syncs master, derives the next patch version from the latest published annotated vX.Y.Z tag, installs dependencies, builds, and checks the package with a publish dry run. It then commits the version files, creates an annotated tag, atomically pushes master and that tag, publishes to npm, and verifies the published version before returning. The Git push is atomic, but npm publication is a subsequent operation and cannot be rolled back by that push. The command requires an npm login with publish rights; publishing is not delegated to GitHub Actions.

If publishing fails after the commit and tag were pushed, inspect the failure and resume that exact tagged release with npx release-patch --resume. The release tool supports patch releases only; minor and major releases require a separately defined process.

Runtime adapters

Rampway resolves runtimes through a small adapter registry. Built-in adapters are compose, none, and rollbridge; future adapters can register a runtime type without changing the deploy lifecycle core. Runtime adapters implement plan() and deploy(...). Optional prepare(...) and commit(...) methods participate in secret-free known-good state, and optional validate, status, logs, and recover methods are exposed by the generic runtime commands.

Rollbridge runtime options:

• command — shell command used to invoke Rollbridge, defaulting to npx rollbridge.
• packageDir — release-relative directory where Rollbridge commands run.
• config — optional Rollbridge config path passed as --config.
• daemonLogPath, daemonPidPath, and daemonStartTimeoutMs — optional daemon flags forwarded to rollbridge deploy.
• versionPath — optional shared file where Rampway records the deployed Rollbridge package version.
• socketPath — optional Rollbridge socket removed after a version-change shutdown if a stale daemon leaves it behind.

When versionPath is configured, Rampway reads the release's installed Rollbridge package version before deploy. If it differs from the recorded version and the current runtime is responsive, Rampway shuts down the current Rollbridge daemon, removes configured stale daemon artifacts, deploys the new release, and records the new version.

Compose runtime

Use runtime: {type: "compose", composeRoot, handoffCommand, healthCommand} when an application is managed by a trusted, fixed Docker Compose deployment. Rampway executes the static handoff command and then the static health command from the absolute composeRoot. It records only a digest and the root in known-good runtime state, never command text or secrets. See the config reference for the strict field contract and rollback behavior.

Safety model

Rampway prepares a complete release before flipping current. If a deploy fails before publish, current remains unchanged. Rollbridge runtime deploys are validated and health-checked with rollbridge status before current is updated. Cleanup never removes the current release or a release referenced by active or draining runtime processes. Long-running drains remain Rollbridge-owned background work outside deploy completion and the Rampway deploy lock. Rollback changes current to a previously prepared release and records a deployment event.