Your first system

A project is a repository with a bluetext.toml in it. A system is a deployable arrangement of components inside that project. Most repositories hold one system; the platform's own holds two.

Start with the manifest, because every other command looks for it:

mkdir shop && cd shop
printf 'name = "shop"\n' > bluetext.toml
b system create shop

That writes systems/shop/system.toml with one environment in it and the rest commented out. b validate already passes, over a system with no components.

Let validation lead

b validate reads the whole file set and cross-references it. Run it after every change: it names what is missing and where, so it is the fastest way to learn the model. The steps below are what it says as you go.

Add a component. A component is one part of the system that is separately deployable. It declares its kind, which decides what else it may say, and the interfaces it serves:

# systems/shop/components/api/component.toml
kind = "online-service"

[interfaces.orders]
kind = "bluetext-api"

error[no-variants] a component has at least one variant:
  add a file under `variants/`

Add a variant. The component says what it is; a variant says what it is made from. One component can have several, one per way of being built or obtained, and the environment picks between them.

# systems/shop/components/api/variants/main.toml
kind          = "source"
toolchain     = "cargo"
base-image    = "gcr.io/distroless/cc"
serves.orders = { port = 8080 }

validate: ok — 1 system(s), 1 component(s), 1 variant(s), 1 warning(s)
warning[product-crate-absent] the crate goes at
  `systems/shop/src/components/api/main/` — there is no Cargo.toml there yet

The system validates, and the warning is doing its job. Declaring a component before writing its code is the normal order, so the platform grades a missing crate as a warning rather than an error. It becomes a real problem only when you try to deploy.

Say where it lands. An environment is what exists; a deploy config is where that lands. b system create leaves one commented out:

[deploy-configs.local]
environment    = "local"
dev-loop       = true
online-service = "local"

The keys are component kinds. online-service = "local" binds every online-service component in that environment to a cluster on this machine, which needs no target declaration of its own.

Make somewhere for it to land

A deploy converges a system into a place that already exists. Creating that place is a separate verb, run once per target rather than per deploy:

b provision local

For a cluster on your own machine that creates it with k3d and installs what every cluster here needs. It wants docker and k3d on your PATH, and no cloud account or credentials. Run it again whenever you like: it converges, so a second run against a standing target reports that nothing needed doing.

Skip it and the deploy says so, naming the cluster that does not exist yet.

The four commands

deploy validates and generates first, so there is no way to deploy a system that does not validate, and no way to build against a stale generated client.

Then run it

b deploy local

At this point the api has no crate yet, which is what that warning was about, so the deploy refuses and says where the crate goes. Writing a service covers that crate and its handlers, and Writing a part covers the business logic behind it.

One thing to know before you start on either: while the core is unpublished, a system's crates depend on it by relative path, so compiling one needs a checkout of the platform repository beside your own. Declaring, validating and provisioning need only b.

What to read next

The rest of this guide walks a system that already exists, todo, which has a page, an api, a store, an identity server, a gateway and a command-line client. Each page takes one part of it and shows the declaration that produces it.