# A First Look at Build

> Deploy a Node.js app with Build, explore config, logs, scaling, and PostgreSQL from the CLI, then set up GitHub deploys, pipelines, and rollback.

- **Collection:** Blog post
- **Published:** 2026-10-19
- **Updated:** 2026-11-16
- **Author:** Anthony Campolo
- **Canonical URL:** https://ajcwebdev.com/first-look-build/
- **Markdown URL:** https://ajcwebdev.com/first-look-build/index.md
- **JSON URL:** https://ajcwebdev.com/first-look-build/index.json

---

## Introduction

[Build](https://build.io/) is a platform as a service for deploying applications and managing their infrastructure. In this Build CLI tutorial, we'll deploy a small Node.js app, then use the CLI to change its configuration, read logs, scale processes, and ship updates. An optional PostgreSQL add-on will demonstrate how Build connects managed services to a running app.

The application is a single Express server. Its job is to give us something working to deploy so we can explore Build's features.

After account activation and CLI login, the main walkthrough stays in the terminal. We'll finish with optional dashboard features: connecting GitHub, creating pipelines, enabling review apps, and restoring an earlier build.

### What We'll Cover

- [Install the tools](#install-the-tools)
- [Create the app](#create-the-app)
- [Deploy with Git](#deploy-with-git)
- [Explore Build features](#explore-build-features)
- [Optional: add a managed database](#optional-add-a-managed-database)
- [Optional: explore dashboard features](#optional-explore-dashboard-features)
- [Clean up](#clean-up)

### Before You Start: Account and Costs

Create a [Build account](https://app.build.io/users/sign_up), complete any email verification, and wait for account activation if prompted. Choose the account and team you intend to use, then complete the required plan and payment setup before installing the CLI. This walkthrough uses paid resources.

Review [Build's current pricing](https://build.io/pricing) before continuing. At the time of this update, Hobby is listed at $9/month with 350 dyno-hours; Developer-plan add-ons are purchased individually. These are separate cost considerations:

| Resource | When this tutorial uses it |
| --- | --- |
| Account plan | Activated during signup; remains subscribed after resource cleanup. |
| App compute | Running the first web process, briefly scaling to two, and optionally running pipeline or review apps consumes compute capacity. |
| Optional PostgreSQL add-on | Provisioned only in the database section; remains allocated until destroyed. |

Check your selected plan's capacity and the add-on's current price. A dashboard estimate of monthly usage is not a receipt for money already charged. Check billing and usage in your account rather than adding dashboard figures together or assuming the database is included in the account plan. The [cleanup section](#clean-up) explains resource teardown and subscription management separately.

## Install the Tools

Use a [Bash](https://www.gnu.org/software/bash/) or [Zsh](https://www.zsh.org/) terminal. Get the tooling for your operating system from these official installation guides:

- [Node.js 24 or newer](https://nodejs.org/en/download), including npm.
- [Git](https://git-scm.com/install/).
- [curl](https://curl.se/download.html).
- [Build CLI](https://docs.build.io/guides/cli/).

You'll also need a text editor. The examples use [nano](https://www.nano-editor.org/download.php) to edit `.env`; you can open that file in your preferred editor instead.

Log in to Build; this opens a browser to authorize the CLI:

```sh
bld login
```

Confirm the signed-in account:

```sh
bld whoami
```

List the teams available to your account:

```sh
bld teams
```

The [login flow](https://docs.build.io/guides/cli/) also configures Git authentication, so the deployment below uses the app's HTTPS Git URL.

## Create the App

Create a new project outside an existing Git repository. Use `build-demo` as the working directory for the remaining commands:

```sh
mkdir build-demo
cd build-demo
git init -b main
mkdir src
```

Create `package.json` in the project root. This enables ECMAScript modules, requires Node.js 24 or newer, and defines the start and syntax-check scripts:

```json
{
  "name": "build-demo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "start": "node src/server.js",
    "check": "node --check src/server.js"
  }
}
```

Install Express:

```sh
npm install --save-exact express@5.3.0
```

Create `src/server.js`:

```js
import express from "express";

const app = express();

app.get("/", (req, res) => {
  console.log(`${req.method} ${req.path}`);
  res.json({ message: process.env.APP_MESSAGE ?? "Hello from Build v1" });
});

app.get("/health", (req, res) => res.json({ ok: true }));

app.listen(Number(process.env.PORT ?? 3000), "0.0.0.0", () => {
  console.log("App is listening");
});
```

Build supplies `PORT` at runtime. Listening on `0.0.0.0` lets its router reach the process. `APP_MESSAGE` gives us a config var to change after deployment.

Create `.gitignore` in the project root to keep dependencies, local settings, and generated files out of Git:

```text
node_modules/
.env
.build-app.json
.build-addon.json
.build-check.mjs
```

Create `Procfile` alongside `package.json` to tell Build how to start the web process:

```text
web: npm start
```

Check the source and start the app:

```sh
npm run check
npm start
```

In a second terminal, request the local app:

```sh
curl --fail-with-body -sS http://127.0.0.1:3000/
```

You should receive:

```json
{"message":"Hello from Build v1"}
```

Stop the local server with Ctrl+C. Continue from `build-demo` to deploy it.

## Deploy with Git

Commit the working app, including the generated lockfile. `.gitignore` keeps local settings and generated files out of the commit:

```sh
git add .
git commit -m "Create a small Build demo"
```

Save the deployment settings in `.env`. The commands below generate an app name and open the file in nano. Set `TEAM` to the exact team name shown by `bld teams`, keeping quotes around names that contain spaces. Save with Ctrl+O, press Enter, then exit with Ctrl+X. Review the printed team and app before creating this disposable app:

```sh
printf '%s\n' 'TEAM=""' > .env
node -p '"APP=build-demo-" + Date.now()' >> .env
nano .env
node --env-file=.env -e 'console.log({ team: process.env.TEAM, app: process.env.APP })'
```

Each command reads its saved values with Node's built-in `--env-file=.env` flag. For example, `$(node --env-file=.env -p 'process.env.APP')` supplies the app name directly to `bld`. Run these commands from `build-demo`; they need no exported variables or reload script. Node gives an already exported value precedence over the file, so use a fresh terminal if you previously exported these names. See the [Node documentation](https://nodejs.org/api/cli.html#--env-filefile) for that behavior.

Create the app, record `CREATED_APP` only after creation succeeds, and save the actual app metadata. Keep `CREATED_APP` as the original creation record; cleanup uses it even if you later select other pipeline apps:

```sh
node --env-file=.env -e 'if (!process.env.TEAM?.trim() || !process.env.APP?.trim()) throw new Error("Set TEAM and APP in .env first")' &&
  bld apps:create "$(node --env-file=.env -p 'process.env.APP')" \
    -t "$(node --env-file=.env -p 'process.env.TEAM')" -r us-east-1 &&
  node --env-file=.env -p '"CREATED_APP=" + process.env.APP' >> .env &&
  bld apps:info -a "$(node --env-file=.env -p 'process.env.APP')" -j > .build-app.json
```

Build's default stack and language detection handle the Node.js application. The root `package.json` declares dependencies, and the `Procfile` declares the web process. See the [deployment guide](https://docs.build.io/guides/deploying-applications/) for those conventions.

Save the public HTTP URL and Git deployment URL returned by Build into `.env`:

```sh
node -e '
  const app = require("./.build-app.json");
  if (["web_url", "git_url"].some(key => typeof app[key] !== "string" || !app[key].trim())) throw new Error("Missing app URL or Git URL");
  console.log("APP_URL=" + JSON.stringify(app.web_url.replace(/\/+$/, "")));
  console.log("GIT_URL=" + JSON.stringify(app.git_url));
' >> .env
```

`APP` is the app name, `APP_URL` is its public HTTP address, and `GIT_URL` is its Git deployment endpoint. The Node command validates the metadata and removes the public URL's trailing slash before saving it, so later commands can append `/` or `/db`. The ignored JSON preserves the original metadata; subsequent commands read the values saved in `.env`. Save literal values in that file; Node does not expand references to other variables.

If app creation or metadata capture fails, inspect `bld apps` before retrying. To recover an existing app's URLs, rerun the `apps:info` metadata read and URL-saving command above; do not repeat app creation just to recover a value. When refreshing a saved value, update its existing line in `.env` rather than accumulating duplicate entries.

### Verify Changes Before Continuing

Deployment and process commands can return before the requested state is visible. This reusable checker waits for three consecutive matching checks, makes at most two minutes of attempts, and limits each HTTP request or CLI read to five seconds.

Create `.build-check.mjs` in the `build-demo` project root, alongside `package.json`, and paste in this JavaScript:

```js
import { execFileSync } from "node:child_process";
import { setTimeout as delay } from "node:timers/promises";

const [mode, target, expected] = process.argv.slice(2);
const modes = ["message", "database", "web", "addon", "removed"];
if (!modes.includes(mode) || !target ||
    (["message", "web", "removed"].includes(mode) && expected === undefined) ||
    (mode === "web" && (!Number.isInteger(Number(expected)) || Number(expected) < 0))) {
  console.error("Usage: node .build-check.mjs <message|database|web|addon|removed> <URL|app|addon> [expected]");
  process.exit(1);
}

const deadline = Date.now() + 120_000;
let consecutive = 0;
let result;
const readBld = (...args) => JSON.parse(execFileSync("bld", args, {
  encoding: "utf8",
  timeout: Math.max(1, Math.min(5000, deadline - Date.now())),
  killSignal: "SIGKILL",
  stdio: ["ignore", "pipe", "pipe"],
}));

while (Date.now() < deadline) {
  let matches = false;
  try {
    if (mode === "message" || mode === "database") {
      const response = await fetch(target, {
        cache: "no-store",
        signal: AbortSignal.timeout(Math.max(1, Math.min(5000, deadline - Date.now()))),
      });
      result = await response.json();
      matches = response.ok && (mode === "message"
        ? result.message === expected
        : typeof result.time === "string" && Number.isFinite(Date.parse(result.time)));
    } else if (mode === "web") {
      const groups = readBld("ps", "-a", target, "-j");
      if (!Array.isArray(groups) || !groups.every(group =>
        typeof group?.type === "string" && Number.isInteger(group.quantity) &&
        group.quantity >= 0 && Array.isArray(group.processes))) throw new Error("Invalid process data");
      const web = groups.filter(group => group.type === "web");
      const processes = web.flatMap(group => group.processes);
      matches = web.reduce((total, group) => total + group.quantity, 0) === Number(expected) &&
        processes.length === Number(expected) &&
        processes.every(process => process.status === "Running");
    } else if (mode === "addon") {
      matches = readBld("addons:info", target, "-j").state === "provisioned";
    } else {
      const addons = readBld("addons", "-a", target, "-j");
      matches = Array.isArray(addons) && addons.every(addon =>
        typeof addon?.id === "string" && typeof addon.state === "string") && addons.every(addon =>
        addon.id !== expected || addon.state === "deprovisioned");
    }
  } catch {
    // A failed request, CLI read, or JSON parse is an unmet check.
  }
  consecutive = matches ? consecutive + 1 : 0;
  if (consecutive === 3) {
    console.log(`Verified ${mode}: ${target}`);
    if (mode === "message" || mode === "database") console.log(JSON.stringify(result));
    process.exit(0);
  }
  console.log(`Waiting for ${mode}: ${target} (${consecutive}/3 matching checks)`);
  await delay(Math.max(0, Math.min(5000, deadline - Date.now())));
}
console.error("Expected state was not verified within two minutes. Stop this step and inspect status and logs.");
process.exit(1);
```

A nonzero exit means the step is incomplete. Stop and use [Troubleshooting](#troubleshooting) before making another change; an agent should report the failed expectation. This two-minute limit is a tutorial checkpoint, not a promise about provisioning time. After inspecting a slow operation, rerun its check without repeating the resource-creation command.

Add the app's Git URL as a remote, then push:

```sh
git remote add build "$(node --env-file=.env -p 'process.env.GIT_URL')"
git push build main
```

Build's Git endpoint deploys its remote `main` branch. If your local branch has another name, use `git push build HEAD:main`. This direct [Git deployment](https://docs.build.io/guides/deploying-applications/#37-deploying-with-git) works without connecting a GitHub repository.

Ensure one web process is running:

```sh
bld ps:scale web=1 -a "$(node --env-file=.env -p 'process.env.APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1
```

After the process check passes, verify the deployed greeting at the public URL saved in `.env`:

```sh
node .build-check.mjs message \
  "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
```

Expect `{"message":"Hello from Build v1"}`. Inspect the build and deployment records as well:

```sh
bld builds -a "$(node --env-file=.env -p 'process.env.APP')"
bld deployments -a "$(node --env-file=.env -p 'process.env.APP')"
```

Confirm that the initial build succeeded and a deployment is current (`*`). Keep one web process throughout the configuration and update exercises; scaling comes afterward.

## Explore Build Features

### Change Configuration

Set the message through Build's config vars:

```sh
bld config:set APP_MESSAGE='Configured through Build' -a "$(node --env-file=.env -p 'process.env.APP')"
bld config:get APP_MESSAGE -a "$(node --env-file=.env -p 'process.env.APP')"
```

The `config:get` command should print `Configured through Build`. Build's [documented configuration behavior](https://docs.build.io/guides/configuration/#when-config-vars-change) is to restart dynos with the new values without redeploying. Verify the running application separately:

```sh
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
  node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Configured through Build'
```

The same deployed code now returns:

```json
{"message":"Configured through Build"}
```

If this check times out or responses alternate, the change has not been verified. Read `bld ps -a "$(node --env-file=.env -p 'process.env.APP')"` and `bld logs -a "$(node --env-file=.env -p 'process.env.APP')" --count 100`, then compare the saved value above with the hosted environment:

```sh
bld run --no-tty --exit-code -a "$(node --env-file=.env -p 'process.env.APP')" printenv APP_MESSAGE
```

Expect `Configured through Build`; empty output or a nonzero exit is a failed check. Inspect only this demo variable. A manually invoked restart does not prove that the config change restarted the app automatically. Avoid scaling or repeatedly redeploying to diagnose this step. You can continue reading logs or [clean up](#clean-up) if it remains unresolved; first remove and verify the override as shown in the update section before continuing with code changes.

### Read Logs

Fetch recent output from the app:

```sh
bld logs -a "$(node --env-file=.env -p 'process.env.APP')" --count 100
```

Look for `App is listening` and the `GET /` entries written by our requests. To stream new output, use:

```sh
bld logs -a "$(node --env-file=.env -p 'process.env.APP')" --tail --process web
```

Make a request in your browser or another terminal to produce another entry. Ctrl+C stops the log viewer. Build's [logs guide](https://docs.build.io/guides/logs-and-monitoring/) explains its application and build log sources.

### Run a Command in the Hosted Environment

Start a temporary one-off process and read the message config var:

```sh
bld run --no-tty --exit-code -a "$(node --env-file=.env -p 'process.env.APP')" printenv APP_MESSAGE
```

It should print `Configured through Build`. The process uses the deployed app's environment, and `--exit-code` forwards its exit status. The current [one-off command implementation](https://github.com/buildio/cli/blob/v1.1.143/src/commands/run.cr) supports Unix systems and connects through the region's SSH endpoint.

### Deploy an Update and Inspect Its History

Remove the config override so the response uses the message in our source:

```sh
bld config:unset APP_MESSAGE -a "$(node --env-file=.env -p 'process.env.APP')"
bld config:get APP_MESSAGE -a "$(node --env-file=.env -p 'process.env.APP')" -j
node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
```

The `config:get` output should be `{}`, confirming the override is gone, and the running app should return v1. Verify both before editing the source; a lingering config override would hide the code change.

In `src/server.js`, change `Hello from Build v1` to `Hello from Build v2`. Check, commit, and push the edit:

```sh
npm run check
git add .
git commit -m "Update the greeting"
git push build main
```

Inspect the build and deployment records:

```sh
bld builds -a "$(node --env-file=.env -p 'process.env.APP')"
bld deployments -a "$(node --env-file=.env -p 'process.env.APP')"
```

The CLI marks the current deployment with `*`. Confirm the new build succeeded, then verify one running process and the updated response:

```sh
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
  node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v2'
```

Expect `Hello from Build v2`. To undo this particular demo edit while it is still the latest commit, revert it and push again:

```sh
git revert --no-edit HEAD
git push build main
bld builds -a "$(node --env-file=.env -p 'process.env.APP')"
bld deployments -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
```

The next deployment should return `Hello from Build v1`. This creates a new commit and rebuilds the reverted source.

### Scale and Restart Processes

After the configuration and code-update checks pass, briefly run two copies of the web process. Each additional dyno consumes account capacity:

```sh
bld ps:scale web=2 -a "$(node --env-file=.env -p 'process.env.APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 2
```

Expect two running web processes. Restart them, verify their status, then return to one instance before continuing:

```sh
bld ps:restart web -a "$(node --env-file=.env -p 'process.env.APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 2
```

Check the recent startup or restart timestamps in `bld ps -a "$(node --env-file=.env -p 'process.env.APP')"` and `bld logs -a "$(node --env-file=.env -p 'process.env.APP')"`; a running-process count alone does not prove the restart occurred.

```sh
bld ps:scale web=1 -a "$(node --env-file=.env -p 'process.env.APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
  node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
```

Do not continue until only one running web process remains. A scale command returning no output is not confirmation that scaling has finished. See [scaling and performance](https://docs.build.io/guides/scaling-and-performance/) for process sizes and counts.

## Optional: Add a Managed Database

The app is already deployed. We can now use a PostgreSQL add-on to demonstrate Build's managed services. We'll query the database's current time to confirm the connection. To skip this paid resource, [continue to the dashboard exercises](#optional-explore-dashboard-features) or [finish and clean up](#clean-up).

Install the PostgreSQL client:

```sh
npm install --save-exact pg@8.23.1
```

Replace `src/server.js` with this version, which adds a `/db` endpoint:

```js
import express from "express";
import pg from "pg";

const app = express();
const databaseUrlKey = process.env.DATABASE_URL_KEY ?? "DATABASE_URL";
const databaseUrl = process.env[databaseUrlKey];
const pool = databaseUrl
  ? new pg.Pool({ connectionString: databaseUrl, max: 2, connectionTimeoutMillis: 5000 })
  : null;
pool?.on("error", () => console.error("Database connection failed"));

app.get("/", (req, res) => {
  console.log(`${req.method} ${req.path}`);
  res.json({ message: process.env.APP_MESSAGE ?? "Hello from Build v1" });
});

app.get("/health", (req, res) => res.json({ ok: true }));

app.get("/db", async (req, res) => {
  if (!pool) return res.status(503).json({ error: "Attach a database first" });
  try {
    const { rows } = await pool.query("SELECT CURRENT_TIMESTAMP AS time");
    res.json(rows[0]);
  } catch {
    res.status(503).json({ error: "Database unavailable" });
  }
});

app.listen(Number(process.env.PORT ?? 3000), "0.0.0.0", () => {
  console.log("App is listening");
});
```

The app still serves its greeting without a database. `/health` checks the web process; `/db` checks the optional database connection. `DATABASE_URL_KEY` will contain the **name** of the connection variable supplied by your add-on. The app reads the connection string from that named variable, with `DATABASE_URL` as a fallback. This avoids copying credentials into another config var or assuming every add-on uses the same name.

Commit and deploy the new endpoint:

```sh
npm run check
git add .
git commit -m "Add a database connection check"
git push build main
bld builds -a "$(node --env-file=.env -p 'process.env.APP')"
bld deployments -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
  node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
```

Confirm the database-endpoint build succeeded and is current in the deployment list. The greeting alone does not prove that `/db` has been deployed.

Inspect the available add-on services and PostgreSQL plans:

```sh
bld addons:services
bld addons:plans schema-to-go
```

Review the [current plans](https://docs.build.io/guides/addon-services/#schematogo) and the price printed by `addons:plans`. `schema-to-go:basic` is listed at $9/month at the time of this update; Developer-plan add-ons are purchased separately. It remains allocated until destroyed. Proceed only after accepting this paid resource; an agent should obtain authorization for it before running the next command. Provision it once and capture its ID:

```sh
bld addons:create schema-to-go:basic \
  -a "$(node --env-file=.env -p 'process.env.APP')" -j > .build-addon.json &&
  node -e '
    const { id } = require("./.build-addon.json");
    if (typeof id !== "string" || !id.trim()) throw new Error("Missing add-on ID");
    console.log("ADDON_ID=" + JSON.stringify(id));
  ' >> .env &&
  node .build-check.mjs addon "$(node --env-file=.env -p 'process.env.ADDON_ID')"
```

If creation returns an error or the saved JSON has no ID, inspect `bld addons -a "$(node --env-file=.env -p 'process.env.APP')"` before retrying; a request might have created a resource despite an interrupted response. Do not overwrite a saved add-on record by repeating creation. A provisioning timeout means inspect and rerun the check, not create a second database.

Once the add-on is `provisioned`, inspect it with the CLI. The output lists connection-variable **names**, without revealing their values:

```sh
bld addons:info "$(node --env-file=.env -p 'process.env.ADDON_ID')"
```

Use the PostgreSQL connection URL variable listed by the add-on. The [add-on guide](https://docs.build.io/guides/addon-services/#provisioning-an-add-on) describes automatic config attachment, but the walkthrough received a provider-specific variable rather than the documented `DATABASE_URL`. Discover the actual name instead of guessing its spelling. If no connection-variable name is shown, list only the app's configuration variable names, then identify the connection URL using the add-on's documentation or dashboard:

```sh
bld config -a "$(node --env-file=.env -p 'process.env.APP')" -j |
  node -e 'try { console.log(Object.keys(JSON.parse(require("node:fs").readFileSync(0, "utf8"))).join("\n")); } catch { process.exitCode = 1; }'
```

Open `.env` and add `DATABASE_URL_KEY` with that variable's exact name as its quoted value. Save and close the file. This is the connection-variable name listed by the add-on, not the connection string. Verify that the hosted variable has a value without printing the credentials, then tell the application which key to read:

```sh
(
  set -e
  set -o pipefail

  nano .env

  node --env-file=.env -e 'if (!process.env.DATABASE_URL_KEY?.trim()) throw new Error("Set DATABASE_URL_KEY in .env first")' &&
    bld config:get "$(node --env-file=.env -p 'process.env.DATABASE_URL_KEY')" \
      -a "$(node --env-file=.env -p 'process.env.APP')" -j |
    node --env-file=.env -e '
      try {
        const config = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
        const value = config[process.env.DATABASE_URL_KEY];
        process.exitCode = typeof value === "string" && value.length > 0 ? 0 : 1;
      } catch {
        process.exitCode = 1;
      }
    ' &&
    bld config:set \
      "DATABASE_URL_KEY=$(node --env-file=.env -p 'process.env.DATABASE_URL_KEY')" \
      -a "$(node --env-file=.env -p 'process.env.APP')"
)
```

If the presence check fails, stop and identify the correct connection variable before proceeding. `DATABASE_URL_KEY` stores a name such as the one you just inspected; it never stores the URL itself. Confirm the saved name and the deployed database query:

```sh
bld config:get DATABASE_URL_KEY -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
  node .build-check.mjs database "$(node --env-file=.env -p 'process.env.APP_URL')/db"
```

The `/db` response contains the database server's current time, for example:

```json
{"time":"2026-10-20T15:00:00.000Z"}
```

Your timestamp will differ. A successful `/db` check verifies that the deployed application can use the managed database. If it fails, check the current build, provisioning state, selected variable name, and runtime configuration using [Troubleshooting](#troubleshooting). Do not infer success from a healthy `/` or `/health` response.

Keep the app and database available if you want to [continue to the dashboard exercises](#optional-explore-dashboard-features). If you're finished, [go to cleanup](#clean-up).

## Optional: Explore Dashboard Features

We've deployed and operated the app, shipped an update, and optionally connected a managed database from the terminal. The following features need dashboard setup in CLI `1.1.143`. Explore them while the app is running. **Run cleanup only after your last optional exercise.** You can also [skip these exercises and clean up now](#clean-up).

### Connect GitHub and Enable Automatic Deploys

Push this project to a GitHub repository you control. Open the app in the [Build dashboard](https://app.build.io/), then:

1. Open **Deploy**, find **Connection**, select the GitHub organization and repository, and click **Connect**.
2. Under **Automatic Deploys**, select the branch to deploy and click **Enable Automatic Deploys**.

Subsequent pushes to that GitHub branch trigger deployments. For a manual deployment, use **Manual Deploy**, select the branch, and click **Deploy Branch**. These [GitHub deployment controls](https://docs.build.io/guides/deploying-applications/#enabling-automatic-deploys) are an optional extension to the direct Git push workflow we already used.

If the repository has CI checks, the dashboard can also wait for them before deploying. Add your tests and an `npm test` script before enabling that gate.

### Create a Pipeline and Promote a Build

A pipeline groups apps into stages. Use disposable demo apps for this exercise. If you already have a pipeline with demo apps, list the available apps, then add their actual names to `.env` as `STAGING_APP` and `PRODUCTION_APP`. Save literal app names, not references to other variables. Skip the creation block below when using existing apps. These selections are separate from the `CREATED_APP` and `CREATED_PRODUCTION_APP` cleanup records:

```sh
bld apps
nano .env
```

For a new pipeline, skip the existing-app block above. The first command below saves the tutorial app's actual name as `STAGING_APP` and generates `PRODUCTION_APP`. Creating the second app consumes additional compute when running; review your capacity before proceeding. Record `CREATED_PRODUCTION_APP` only if creation succeeds, and leave that ownership record unchanged when selecting pipeline targets later:

```sh
node --env-file=.env -p \
  '"STAGING_APP=" + process.env.APP + "\nPRODUCTION_APP=build-prod-" + Date.now()' >> .env

node --env-file=.env -e 'if (!process.env.PRODUCTION_APP?.trim() || !process.env.TEAM?.trim()) throw new Error("Set PRODUCTION_APP and TEAM in .env first")' &&
  bld apps:create "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')" \
    -t "$(node --env-file=.env -p 'process.env.TEAM')" -r us-east-1 &&
  node --env-file=.env -p \
    '"CREATED_PRODUCTION_APP=" + process.env.PRODUCTION_APP' >> .env
```

For a new pipeline, in the dashboard, choose **New + → New Pipeline**, name the pipeline, and assign these apps to its **staging** and **production** stages. If you use an existing pipeline, skip this step. Pipeline creation and stage assignment use the dashboard; the CLI can then inspect and promote the configured apps.

Compare the stages from the terminal:

```sh
bld pipelines:diff -a "$(node --env-file=.env -p 'process.env.STAGING_APP')"
```

Save the staging app's actual URL and request its current greeting. When nano opens, add `STAGING_MESSAGE` to `.env` with the expected greeting from the staging app's configuration or deployed source, such as `STAGING_MESSAGE="Hello from Build v1"` for this tutorial. Save and close the file. The remaining commands verify that greeting before promoting the build; a failed metadata read, request, or check stops the sequence.

```sh
(
  set -e
  set -o pipefail

  bld apps:info -a "$(node --env-file=.env -p 'process.env.STAGING_APP')" -j |
    node -e '
      const { web_url } = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
      if (typeof web_url !== "string" || !web_url.trim()) throw new Error("Missing app public URL");
      console.log("STAGING_URL=" + JSON.stringify(web_url.replace(/\/+$/, "")));
    ' >> .env

  curl --fail-with-body -sS --connect-timeout 5 --max-time 5 \
    "$(node --env-file=.env -p 'process.env.STAGING_URL')/"

  nano .env
  node --env-file=.env -e 'if (!process.env.STAGING_MESSAGE?.trim() || !process.env.PRODUCTION_APP?.trim()) throw new Error("Set STAGING_MESSAGE and PRODUCTION_APP in .env first")'

  node .build-check.mjs message \
    "$(node --env-file=.env -p 'process.env.STAGING_URL')/" \
    "$(node --env-file=.env -p 'process.env.STAGING_MESSAGE')"
  bld pipelines:promote \
    -a "$(node --env-file=.env -p 'process.env.STAGING_APP')" \
    --to "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')"
  bld deployments -a "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')"
)
```

Ensure the target has a running web process and save its actual URL. Read its own `APP_MESSAGE` configuration, then add `PRODUCTION_MESSAGE` to `.env` with the expected greeting in quotes. Use its configured message when present, or the fallback greeting in the promoted source (`Hello from Build v1` for this tutorial). Save and close the file before the checks run:

```sh
(
  set -e
  set -o pipefail

  bld ps:scale web=1 -a "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')"

  bld apps:info -a "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')" -j |
    node -e '
      const { web_url } = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
      if (typeof web_url !== "string" || !web_url.trim()) throw new Error("Missing app public URL");
      console.log("PRODUCTION_URL=" + JSON.stringify(web_url.replace(/\/+$/, "")));
    ' >> .env

  bld config:get APP_MESSAGE \
    -a "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')" -j

  nano .env

  node .build-check.mjs web \
    "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')" 1 &&
    node .build-check.mjs message \
      "$(node --env-file=.env -p 'process.env.PRODUCTION_URL')/" \
      "$(node --env-file=.env -p 'process.env.PRODUCTION_MESSAGE')"
)
```

[Promotion](https://docs.build.io/guides/cicd-and-pipelines/#93-staging-and-production-promotion) deploys the existing build artifact. The target keeps its own configuration and database; staging config vars and data aren't copied. Enter the target's own `APP_MESSAGE` if present, or the fallback greeting in the source being promoted (`Hello from Build v1` for this tutorial). Confirm the intended deployment is current as well as checking its response. Leave an existing target's settings intact.

### Enable Review Apps

After connecting the pipeline to your GitHub repository, open its settings to enable [review apps](https://docs.build.io/guides/cicd-and-pipelines/#92-review-apps). Configure their creation, cleanup, and environment variables there. Review apps give pull requests separate preview URLs and provision additional app resources.

Record the names of any review apps and add-ons created during this exercise. They are additional cleanup targets; the `CREATED_APP` and `CREATED_PRODUCTION_APP` entries in `.env` automatically track only the main app and a production app created by the block above.

### Restore an Earlier Build

Open the tutorial app's **Activity** tab, find a previous successful build, and choose **Rollback to here**. This restores an earlier deployment artifact through the [dashboard rollback workflow](https://docs.build.io/guides/deploying-applications/#deploying-a-specific-commit).

The `git revert` example earlier creates a new source commit and rebuilds it. Dashboard rollback selects an earlier build; your local Git history stays as it was. If you completed the optional database section, choose a build that includes `/db` when you want to keep that endpoint available.

After rollback, inspect `bld deployments -a "$(node --env-file=.env -p 'process.env.APP')"` and run the response check with the greeting from the build you selected. For example, if you restored the initial build:

```sh
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
  node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
```

After your last dashboard exercise, continue to cleanup below.

## Clean Up

Finish or skip the optional dashboard exercises before running cleanup. If you enabled automatic deploys or review-app creation for the demo, disable those settings first so later pushes or pull requests do not recreate resources. List any review apps and add-ons you created alongside the main and production demo apps.

From `build-demo`, stop the web compute for apps **created by this tutorial**. These commands read `CREATED_APP` and the optional `CREATED_PRODUCTION_APP` from `.env`. Selecting an existing pipeline app does not add it to these ownership records. The production commands are skipped when no tutorial-created production app was recorded:

```sh
(
  set -e

  node --env-file=.env -e 'if (!process.env.CREATED_APP?.trim()) throw new Error("No tutorial app was recorded")'

  bld ps:scale web=0 -a "$(node --env-file=.env -p 'process.env.CREATED_APP')"
  bld ps -a "$(node --env-file=.env -p 'process.env.CREATED_APP')"
  node .build-check.mjs web "$(node --env-file=.env -p 'process.env.CREATED_APP')" 0

  if node --env-file=.env -e 'process.exit(process.env.CREATED_PRODUCTION_APP?.trim() ? 0 : 1)'; then
    bld ps:scale web=0 \
      -a "$(node --env-file=.env -p 'process.env.CREATED_PRODUCTION_APP')"
    bld ps -a "$(node --env-file=.env -p 'process.env.CREATED_PRODUCTION_APP')"
    node .build-check.mjs web \
      "$(node --env-file=.env -p 'process.env.CREATED_PRODUCTION_APP')" 0
  fi
)
```

Each check must confirm desired web quantity zero and no remaining web processes. If a check times out, inspect that app and repeat the check; cleanup is incomplete. After the app stops, its URL may return `no healthy upstream`. That is expected when there is no web process, but an HTTP error alone does not verify that compute or add-ons have been removed.

If you created the optional database, inspect the `ADDON_ID` saved in `.env` before deletion. The conditional skips this step when no add-on ID was recorded:

```sh
(
  set -e
  node --env-file=.env -e ''

  if node --env-file=.env -e 'process.exit(process.env.ADDON_ID?.trim() ? 0 : 1)'; then
    bld addons:info "$(node --env-file=.env -p 'process.env.ADDON_ID')"
  fi
)
```

Confirm this is the disposable database created for this tutorial. Destruction permanently removes the database and its attachments. Then destroy it and verify removal using a successful add-on listing:

```sh
(
  set -e
  node --env-file=.env -e ''

  if node --env-file=.env -e 'process.exit(process.env.ADDON_ID?.trim() ? 0 : 1)'; then
    node --env-file=.env -e 'if (!process.env.CREATED_APP?.trim()) throw new Error("No tutorial app was recorded")' &&
      bld addons:destroy "$(node --env-file=.env -p 'process.env.ADDON_ID')" \
        -a "$(node --env-file=.env -p 'process.env.CREATED_APP')" &&
      node .build-check.mjs removed \
        "$(node --env-file=.env -p 'process.env.CREATED_APP')" \
        "$(node --env-file=.env -p 'process.env.ADDON_ID')"
  fi
)
```

The removal check passes only when the saved ID is absent or marked `deprovisioned`; a failed API request is not removal confirmation. Scaling web processes to zero leaves add-ons allocated until they are destroyed.

Finish in the [Build dashboard](https://app.build.io/):

1. Open the team used for the tutorial. For each review app created during the optional exercise, inspect its resources, remove its disposable add-ons, and delete the app. Verify those resources disappear; do not rely solely on an automatic cleanup setting.
2. Open each app recorded as `CREATED_APP` or `CREATED_PRODUCTION_APP` in `.env`, go to **Settings**, and use the app deletion control. Confirm the exact app name when requested, then verify it no longer appears in the team's app list. CLI `1.1.143` has no app-delete command. Leave pre-existing pipeline apps in place.
3. Check the team's app and add-on inventories for remaining tutorial resources, including anything created during an interrupted request. Remove only resources you created for this walkthrough. Verify that no tutorial web processes or database add-ons remain; remove the optional demo pipeline after its demo apps are gone.
4. Open **Billing** and review the remaining subscription separately. Resource teardown does not cancel the account plan or erase charges already incurred. If you opened the account only for this walkthrough and want to stop its recurring subscription, use the available subscription controls or [contact Build support](https://docs.build.io/need-help/get-support/) if cancellation is not exposed. Confirm the resulting subscription status before considering account cleanup complete.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Login or Git push is rejected | Run `bld whoami` and confirm account activation and team access. |
| The build fails | Read `bld logs -a "$(node --env-file=.env -p 'process.env.APP')" --source build` and check the lockfile and start script. |
| The web process isn't ready | Inspect `bld ps -a "$(node --env-file=.env -p 'process.env.APP')"` and `bld logs -a "$(node --env-file=.env -p 'process.env.APP')"`; confirm the app uses `PORT` and `0.0.0.0`. |
| The configured greeting doesn't appear | Compare `bld config:get APP_MESSAGE -a "$(node --env-file=.env -p 'process.env.APP')" -j`, the narrow hosted `printenv APP_MESSAGE` check, and the HTTP response. Keep one web process; stop the exercise if the expectation remains unmet. |
| The greeting alternates between values | Inspect process count, build and deployment records, and recent logs. A single matching request is insufficient; rerun the checker after investigating. |
| The greeting doesn't change after a push | Confirm the intended build succeeded and is current; check for an old `APP_MESSAGE` override. Verify its removal before testing the source greeting. |
| `/db` returns `503` | Check the current database-endpoint build, add-on provisioning state, and the exact connection key listed by the add-on. Inspect `bld config:get DATABASE_URL_KEY -a "$(node --env-file=.env -p 'process.env.APP')"`; verify the selected connection key is nonempty using the presence check above without printing its value. |
| A scale or restart command returns no output | Inspect `bld ps -a "$(node --env-file=.env -p 'process.env.APP')"` and run the web-count checker. For restarts, also inspect startup/restart timestamps and logs. |
| A provisioning or cleanup check times out | Inspect the saved resource ID and current status. Retry the read check after inspection; do not create another resource or treat an API error as proof of deletion. |
| A one-off command can't connect | Check the region's SSH host and port in `bld apps:info -a "$(node --env-file=.env -p 'process.env.APP')" -j` against your network's outbound rules. |

If you open a new terminal or switch agent sessions, return to the `build-demo` directory containing `.env`. Each command reads that file automatically. Inspect the saved app and its current metadata with:

```sh
bld apps:info -a "$(node --env-file=.env -p 'process.env.APP')" -j
```

The saved `ADDON_ID`, pipeline app names, URLs, expected greetings, and creation records remain in `.env` as you complete those exercises. `.build-app.json` and `.build-addon.json` preserve the original platform responses. If a URL has changed, refresh its existing `.env` entry from `apps:info`. Never rerun a creation block just to recover an identifier.

## Verification Notes

The application examples were checked locally on macOS ARM64 with Node.js `26.12.0`, npm `11.20.0`, Express `5.3.0`, and node-postgres `8.23.1`. Checks covered initial and configured greetings, health, missing database configuration, provider-specific connection-key selection, the `DATABASE_URL` fallback, and safe query failures. Database query checks used a mocked connection pool. Shell examples were syntax-checked in Bash and Zsh.

The polling helper passed 29 local fixture cases covering successful and delayed responses, alternating values, request failures, malformed data, process counts, provisioning, removal, and timeouts. The `.env` capture, JSON processing, command substitution, and cleanup examples use Node's built-in modules. They were checked in Bash and Zsh with a stub CLI, including team names with spaces, existing pipeline apps, and failed operations. Hosted commands and dashboard steps were reviewed against Build's documentation and CLI `1.1.143`; this revision has not been rerun against a live Build account.

## Resources and Links

- [Build documentation](https://docs.build.io/) — platform concepts and guides.
- [CLI installation and authentication](https://docs.build.io/guides/cli/) — installation and login.
- [Git deployment](https://docs.build.io/guides/deploying-applications/#37-deploying-with-git) — push URLs and branch behavior.
- [CLI command reference](https://docs.build.io/reference/cli-reference/) — app, process, config, and history commands.
- [CLI source at v1.1.143](https://github.com/buildio/cli/tree/v1.1.143) — command implementations checked for this walkthrough.
- [Pipelines and GitHub integration](https://docs.build.io/guides/cicd-and-pipelines/) — dashboard setup, promotion, review apps, and CI gates.
- [Add-on provisioning](https://docs.build.io/guides/addon-services/) — managed services and resource lifecycle.
- [Build pricing](https://build.io/pricing) — current platform plans and costs.
- [Node environment-file support](https://nodejs.org/api/cli.html#--env-filefile) — read saved deployment values for each command.
- [node-postgres documentation](https://node-postgres.com/) — connections, pooling, and queries.

## Discover Related Content

- [A First Look at Fly](/first-look-fly/)
