Runs

A run is something bldr keeps running: one or more services, started from a declaration in your build code, backed by the build that produced what they serve.

Declaring one

import { runnable } from "bldr";
import nginxImage from "nginx";

scope.addRunnable(
    "web",
    runnable().service("web", {
        image: nginxImage,
        mounts: [{ source: site, dest: "/usr/share/nginx/html" }],
        ports: [{ host: 8080, pod: 80 }],
    }),
);

A runnable can declare several services and a network between them, so a service that needs a database beside it is one declaration rather than two things you start in the right order.

Starting and managing

bldr run site:web --name "serve the site"
bldr runs                    # what is running
bldr runs attach <RUN-ID>    # stream its logs
bldr runs stop <RUN-ID>

Following a build

The reason to declare a run in build code rather than starting a container yourself:

bldr build --run site/web --watch --name "live"

Now the run follows the build. What a new round costs is decided per service. A mount the runnable marks hot-swappable is swapped under the running pod with no restart. A changed image, a mount that is not hot-swappable, or a mount added or removed restarts that pod and anything that depends on it. A round that rebuilt nothing touches nothing.

Stop the build and the run stays up on the last thing it was given. Stopping a build does not tear down what it started, which is usually what you want and occasionally a surprise.