Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Deployment and releases / DeploymentRead Markdown
    On this page

    Terraform-first deployment

    Use Brix to prepare and verify application inputs, and project-owned Terraform to manage resources, configuration, and traffic. There is no Brix deployment command, target registry, or state manager. Explicit snapshot and artifact publishing can precede Terraform; Brix does not reimplement Terraform. Release publication is separate from application deployment.

    Start with existing infrastructure

    #

    Inspect existing Terraform state, providers, backend, IAM, environment schemas, build setup, and deployment approvals before changing anything. Preserve resources and ownership; use reviewed imports, moved blocks, or state moves and a no-destroy plan when adopting old addresses. Bootstrap the backend separately. Its account may differ from runtime providers: each needs independent guards.

    The editable recipe ships in the installed package at node_modules/brix/templates/deployment/aws-lambda and demonstrates custom Lambda workers without browser assets, existing runtime IAM roles, and a bootstrapped backend. Copy and adapt it to your project; read its README for current invocation details. It is not a universal HTTP/asset deployment module. Use the same project-owned script locally and in CI, with different authentication and approval adapters. Reviewed target tfvars JSON supplies target identity and bindings.

    Uploads and Terraform apply change shared state and require explicit authorization. Script checks are guardrails, not access control; enforce authorization with IAM and protected environments.

    Verify prepared artifacts offline

    #
    import { verifyDeploymentArtifact } from "brix/artifacts";
    
    const verified = await verifyDeploymentArtifact("apps/worker/dist/deployment", {
      target: "aws-lambda",
      source: { revision: approvedRevision, project: "apps/worker", clean: true },
    });
    // Persist verified.manifestSha256 with the deployment record.
    

    This Node-only API checks manifest schema, canonical package hashes, asset inventory, and Lambda safe ZIP limits. Fastly's fastly-compute tarball is verified without extraction. It needs neither credentials nor a checkout. source.clean: true requires a build from a clean checkout; false or omission accepts either. Expected source.project is the app workspace path; build.application is an entry filename, not identity. manifestSha256 hashes the exact deployment.json bytes, not the nested build manifest. Integrity is not provenance attestation, and this is not a validator for arbitrary repackaged ZIPs.

    Prepare all environments before any write

    #
    import { prepareEnvUpload, uploadAwsEnvSnapshot } from "brix/env/upload";
    
    // applications and target come from reviewed project configuration.
    const prepared = [];
    for (const application of applications) {
      prepared.push(
        await prepareEnvUpload({
          root: application.root,
          stage: target.stage,
          bindings: application.bindings,
        }),
      );
    }
    for (const [index, handle] of prepared.entries()) {
      // Project adapter persists the token BEFORE mutation; never print values.
      const requestToken = await persistRequestToken(index);
      const receipt = await uploadAwsEnvSnapshot(handle, {
        accountId: target.accountId,
        region: target.region,
        requestToken,
      });
      await persistReceipt(index, receipt);
    }
    

    These are Node-only APIs. Preparation resolves schema/base/stage once, excludes local files, rejects injected snapshot context, and returns an opaque process-local handle, not serialized values. It does not mutate process.env. Ambient application keys fail unless explicitly named in overrides; internal provider authentication is allowed. Bindings must be declared and non-sensitive. Prepare every application before any upload so a later schema failure cannot leave an earlier application published. The API does not export CI variables.

    Upload validates its inputs before contacting AWS: accountId must be 12 digits, region an explicit AWS region such as eu-west-1, and requestToken 32–64 letters, digits, or hyphens (a crypto.randomUUID() value qualifies). It resolves credentials once for both STS and the write, checks the target account before writing, and uses the explicit region without ambient service endpoint overrides. It checks exact response identity and returns { format: "brix-env-upload-v1", accountId, region, stage, name, arn, versionId }. There is no mandatory readback, automatic retention, or promotion. See environment secrets for the CLI adapter and override consent.

    Persist tokens and receipts durably. The same token and bytes retry idempotently; an error may represent a successful write. Do not blindly generate new tokens or rerun preparation with changed provider values. Inspect remote metadata and reconcile uncertain outcomes without logging secrets.

    Approve the computed plan

    #

    Publish verified packages, then bind exact snapshot ARN/version receipts in Terraform. Protect saved plans because they can contain secrets. Record artifact and snapshot identities with the plan:

    terraform plan -out=deployment.tfplan -var-file=target.tfvars.json
    sha256sum deployment.tfplan
    # Obtain approval for this digest; revalidate artifact bytes before applying.
    terraform apply deployment.tfplan
    

    A protected GitHub environment gate before a job is not approval of the plan computed later. Apply only the digest-approved saved plan, not a regenerated one. For HTTP builds, publish and verify assets before activation and preserve delivery metadata. Terraform owns resource/traffic decisions; health checks are project-defined, and scripts cannot infer health from successful apply.

    Define recovery policy explicitly

    #

    Coordinate concurrency across local and CI, including uploads and approvals, not merely Terraform's backend lock. Define partial-apply recovery by inspecting actual state and provider versions before retrying. Never label a snapshot live solely because apply succeeded. Retain active, rollback, and pending snapshots, packages, and assets; own labels, cleanup, and provider quota limits. AWS may remove unlabeled old versions. Brix does not automatically retain or roll back them.

    Build once and promote the same bytes when possible. Stage-specific CDN origins or build-time values make artifacts specific to those inputs. Validate the candidate with representative events or public HTTP and asset checks before changing traffic; local tests do not establish remote permissions.