Deploy an app to cloud hosting

Cloud hosting on Build Me Web runs your application across preview, staging, and production environments with managed builds, secrets, health checks, and CDN-backed delivery. This quickstart covers creating environments, connecting Git, configuring build and runtime, and promoting to production safely.

Prerequisites: repository access (GitHub, GitLab, or Bitbucket), knowledge of your app’s build command and output directory, and a list of required environment variables for preview vs production. Framework detection covers common Node, static, and containerized setups; custom stacks are welcome when you declare build steps explicitly.

1. Create an environment

In Cloud Environments, create at least preview and production. Preview environments spin up per branch or pull request so stakeholders review real builds. Production is protected: on Managed plans, promotions can require approval and deploy windows.

Optional staging sits between preview and production for integrated QA against shared services (search, payments sandbox, CRM). Keep configuration keys identical across environments; only values and secrets differ. That discipline prevents “works on preview” surprises.

1. Create production with the public hostname you will serve.
2. Create preview with automatic branch URLs and noindex headers enabled.
3. Create staging if multiple teams must validate the same build artifact before prod.
4. Assign who can promote and who can manage secrets.

Environments
├── preview   (per branch, noindex, ephemeral)
├── staging   (shared QA, longer lived)
└── production (protected, approved promote)

Set resource floors for production ahead of campaigns so autoscaling does not cold-start during a launch email. Preview can stay smaller.

2. Connect the repository

Authorize Git access and select the default branch. Build Me Web detects common frameworks (Next.js, static site generators, Node servers) and suggests a build command and output directory. Confirm or override before the first deploy.

Protect the default branch with required checks in your Git host. Treat the Build Me Web build status as a required check so broken main never auto-promotes.

• Monorepos: set the project root and install filter so unused packages are not built every time.
• Private submodules: grant the deploy identity access or vendor the dependency.
• Large binary assets: prefer object storage / CDN uploads over stuffing the Git history.

3. Configure build & runtime

Declare build and runtime in bmw.toml or the environment UI. Store secrets in the environment vault — never commit API keys. Mark variables as runtime-only when they must not appear in client bundles.

bmw.toml
[build]
command = "npm ci && npm run build"
output  = "dist"

[env.production]
NODE_ENV = "production"

# Secrets live in the vault, referenced by name
# DATABASE_URL, SESSION_SECRET, STRIPE_SECRET_KEY

Install dependencies with a lockfile in CI so builds are reproducible. Cache package directories between builds. Fail the build on lint or unit test scripts you consider blocking.

Runtime considerations:

• Set memory and concurrency for server runtimes based on realistic traffic, not laptop defaults.
• Configure health check paths that exercise database connectivity, not only a static HTML file.
• Separate build-time public vars (safe to inline) from runtime secrets.

For container workflows, provide a Dockerfile that runs as a non-root user, exposes the expected port, and keeps image layers lean. Prefer distroless or slim bases when compatible.

4. Promote to production

Push to a feature branch to build a preview. When checks pass and stakeholders approve, merge to the default branch or promote the artifact explicitly. Production uses blue-green cutover: the new version warms, health checks must succeed, then traffic shifts.

1. Verify preview against production-like data (anonymized) and feature flags.
2. Run smoke tests: home, auth, critical write path.
3. Promote with bmw deploy --prod or the UI Promote action.
4. Watch error rate and latency for the first fifteen minutes; keep rollback ownership clear.

Troubleshooting

Build fails on missing env: compare vault keys to what bmw.toml and the app expect; preview and production often diverge by accident.

Health check failing: ensure the probe path does not require auth cookies and that migrations finished before traffic shift.

Client sees old assets: confirm hashed asset URLs and CDN purge for HTML entry points.

Best practices

Keep previews disposable and production boring. Automate promotions from green pipelines, not from laptops. Document rollback in the same runbook as deploy. Pair this quickstart with Zero-downtime deploys and Environments & deploys for approval gates and longer operational detail.

Prerequisites & preparation

Before changing production settings for application deploys, align the people who own content, DNS, analytics, and approvals. A fifteen-minute kickoff that names owners prevents multi-day Slack archaeology later. Capture decisions in the workspace notes so the next teammate inherits context instead of guesswork.

Gather credentials and access: workspace admin or editor role, DNS control when hostnames are involved, payment or API sandbox accounts when money paths are involved, and a shared checklist link. Confirm which environment you will rehearse in — preview first, production only after a green run.

List env vars for preview vs production, confirm Git permissions for the deploy identity, define health check paths, and name who can promote.

Detailed walkthrough

Work the happy path slowly the first time. Narrate what you expect to see after each click: a status badge, a DNS record, a webhook delivery, a Lighthouse metric. When reality diverges, stop and resolve the mismatch instead of clicking ahead — most outages begin as ignored yellow states.

1. Create preview and production with identical configuration keys.
2. Connect the repo; set monorepo roots and build commands explicitly.
3. Store secrets in the vault; mark runtime-only vs build-time public values.
4. Ship a branch preview and smoke-test auth plus the primary write path.
5. Promote with blue-green; observe errors and latency with rollback ownership assigned.

Worked example:

[build]
command = "npm ci && npm run build"
[checks]
health = "/api/health"

Edge cases & failure modes

Plan for partial failure. Networks drop, registrars delay, providers rate-limit, and humans approve the wrong revision. Your runbook should say what “abort” looks like: leave preview up, roll back the release, or freeze campaigns until metrics recover.

• Config key drift between preview and production.
• Health checks that only hit static HTML.
• Migrations incompatible with blue-green overlap.

QA checklist before you announce

• Happy path verified on mobile and desktop
• Failure path messaging reviewed
• Owners named for the first hour after launch
• Rollback or freeze path documented

Operating the change

After launch, watch the metrics that prove the change worked — not vanity charts. Pair quantitative signals with one qualitative check (support ticket themes, sales feedback). Schedule a follow-up within a week to remove temporary flags, raise DNS TTLs, or archive the experiment.

Annotate deploys on dashboards and keep the prior artifact warm through the first traffic peak.

Production promotes deserve a short ceremony: migrations, flags, communications, monitoring. Rehearsal creates speed; skipping steps creates incidents.

Selective monorepo builds reduce the temptation to bypass CI. Long irrelevant builds train bad habits.

Run secrets scanning in CI and rotate anything that leaked into history.

Containers should run non-root and avoid baking secrets into image layers.

Document CLI vs UI promote paths so contractors cannot invent unsafe shortcuts.

Set autoscaling floors before campaigns so cold starts do not greet your launch email.

Practice dependency failure on staging to validate health checks and alerts before customers do.

Prefer promoting immutable artifacts you already tested — rebuilds for production invite “works on preview” drift.

Implementation checklist

Confirm environment variable key parity across preview and production on preview before you promote. Name who approves the change, which environment is authoritative, and what “done” looks like in measurable terms.

Document health check paths that include dependency readiness where the team already looks — workspace notes or the engineering handbook — not only in a meeting memory.

Operating it with your team

Rehearse immutable artifact promotion instead of rebuild-on-promote against written acceptance checks. If you cannot name the verification event (order, DNS lookup, deploy health, or signed API call), you are not ready to announce.

Measure secret scanning and vault rotation discipline with anonymized but realistic data, and keep logs, headers, or screenshots for at least one release cycle so regressions have a baseline.

When you finish this guide, you should be able to explain the happy path, the abort path, and the metrics that prove success. If any of those are fuzzy, revisit the walkthrough with your teammates before you scale traffic, spend, or automation.