Build an application

Four steps, four different effects — and the order is enforced.

TL;DR

• Preview in dev while you build; preview in build before you ship. They serve different files.
• Publishing is refused unless you are previewing, as a build, the exact project you are publishing.
• Publishing spends money on a build node, so you are asked first.
• Publish, promote and release are three separate things. Doing one does not do the others.

Mental model

An application reaches a person through four gates, and each one moves it exactly one step:

  working tree ──preview──▶ what it actually serves
       │
       └──publish──▶ stored source + built image   (a version)
                          │
                          └──promote──▶ the version visitors get
                                            │
                                            └──release──▶ the address answers

The gap that catches people is between those last three. A publish files a version and changes what nobody sees. A promote decides which filed version is served, and still leaves the application's own address answering exactly as a name that does not exist. Only a release turns that address into a page.

The preview is the only place the built artifact is ever looked at. Reading the source does not show it, and neither does a dev server: the dev server reflects the tree as it is edited, while the build serves production output with hashed assets and no hot reload. A build that produces an empty page produces an empty page for the visitor too, and nothing between the publish and their browser says so.

That is why the build preview is a precondition rather than advice. Publishing is refused unless the conversation is previewing, as a build, the project being published — checked against the live preview, so what is published is what is on screen.

Walkthrough

Build against the dev server, then switch the preview to the build and look at what it serves. Publish once that build is one you have seen working; the approval to spend on the build node is asked for at that moment. Then promote the version so visitors are served it, and release the application so its own address answers.

Next steps

• /concepts/applications
• /flows/deploy-and-monitor

For exact flag tables, JSON contracts, and error matrices, see the page in the CLI:

ppl --agent=general docs get flows/build-an-applicationCopy