Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Deployment and releasesRead Markdown
    On this page

    Deployment

    Brix supports Node, AWS Lambda, Cloudflare Workers, and Fastly Compute. Brix builds complete platform artifacts; your deployment infrastructure provisions resources and publishes them.

    Start by choosing where the application will run. Brix prepares the build; your hosting setup owns credentials, domains, assets, and publishing. If your application uses Brix environment loading, prepare a validated snapshot as part of that setup.

    Select a configured platform in vite.config.ts or override it for one command with brix build --platform <platform>.

    Generated HTTP builds contain discovered routes, islands, assets, manifest, and platform adapter. For Lambda, platform: "lambda" uses this assembly; adding handler: "src/handler.ts" replaces it with a fully bundled custom Node worker. Every normal Lambda build emits a packaged, checksummed handoff under dist/deployment/. Consumer CI and infrastructure publish it and own resources, bindings, IAM, smoke checks, traffic, retention, rollback, and any static-site output.

    Choose the runtime before building

    #
    • Use Node for a long-running server or container with a Node runtime and the exact project installation. This is the default and the simplest production path to validate locally.
    • Use Lambda for an AWS-managed invocation lifecycle. Choose generated HTTP assembly for web requests or a custom handler for raw events; the latter does not include pages or islands.
    • Use Cloudflare or Fastly when your hosting system owns Worker bindings and edge delivery. Audit server dependencies for Node-only APIs first. Fastly additionally needs its CLI for Wasm compilation and offers Viceroy-based local execution.
    • A managed React application produces a static browser bundle instead of any of these Hono server targets.

    Before deploying, make brix verify pass, choose the runtime environment snapshot, and establish where assets will be served. A successful build proves artifact preparation, not IAM, secrets, domain/TLS configuration, or provider compatibility. Keep deployment credentials in the delivery workflow, not in build inputs or browser bundles.

    Continue with your target

    #

    Use Terraform-first deployment to inspect and preserve existing infrastructure, verify artifacts, prepare all snapshots before writes, and approve a computed saved plan. Local and CI should use the same project-owned script; Brix supplies primitives, not Terraform state management. Explicit publishing remains separate from activation.

    1. Read build and runtime configuration for every target.
    2. Follow Node and AWS Lambda or Cloudflare and Fastly.
    3. Return to the operational checks and smoke the public candidate before changing traffic.

    Coordinate verified releases with promotion

    #

    For a single root application, opt into brix.release.promotion to deploy immutable stable candidates through ordered stages with Slack approvals. See publishing project releases for complete configuration, controller provisioning, credentials, and failure recovery.

    This does not provide cloud deployment helpers: implement project-owned deploy and health-check scripts, declare built artifacts in release.assets, and never rebuild during promotion. Commands run from the candidate worktree with stage, SHA, and tag environment variables. Your scripts must route stage credentials explicitly, fail on bad deployments, and poll health until the intended candidate is healthy. Generated jobs do not automatically select environment-specific secrets.

    Promotion pushes stable candidate tags but creates no GitHub Release, draft, or prerelease until production deployment and verification succeed. It requires a separately provisioned Node.js 24 controller with persistent local SQLite storage behind HTTPS, not ephemeral Lambda or network disk. No production baseline is imported automatically. There is no automatic rollback or cancellation UI; after runner failure inspect actual deployment state before explicitly retrying. Attempts are dispatched once, with pre-claim failures reconciled against GitHub and missing runs made retryable after ten minutes of successful observation. The controller token is administrative: its holders are trusted to register candidates and attest health, not just inspect status. Already-published tags can be registered after a handoff failure without rebuilding; follow the recovery procedure.