Deploying

Deploying is getting a build off your machine and onto the URL people use, and then knowing — not hoping — that the URL is serving it. One command covers all of that.

carlos deploy -app hello ./hello

It prints where it is deploying to, then shipped, then promoted, and finally live against each hostname. That last line is the one that matters. The others say a write succeeded; only live says a visitor would get the new build.

What the one command is doing

Three steps, and you can run them separately when you want the gap between them.

Shipping hashes your artifact, stores it under its content address, and records a manifest that never changes afterwards. Nothing you serve changes yet. Promoting points a channel at that version — see Channels for what a channel is and when you would have more than one. Then the command watches: it polls the live hostname for the X-Carlos-Version header until that header names the version you shipped, over a 2xx. It gives up after two minutes by default, and -timeout moves that.

The header is also how you check by hand later, and it is worth preferring over anything else you might reach for. A page that looks right can be a cached copy of the old build:

curl -sI https://hello.bdf.oncarlos.com | grep -i x-carlos-version

What you ship

The version defaults to git rev-parse --short HEAD, so a deploy from a clean checkout is already labelled with the commit it came from. -version overrides it.

Binaries are the common case, and -target says what you built for. It defaults to linux-arm64, which is what Carloku runs, so a Go build for this platform is:

GOOS=linux GOARCH=arm64 go build -o hello .

A directory of files ships as a site, with -kind static:

carlos deploy -app hello-site -kind static ./public

Run any of these once from your project and the CLI offers to remember the app and the artifact in .carlos/config. Say yes and the whole release becomes carlos deploy with no arguments, which is the form to put in a Makefile or a git hook.

When it doesn't go live

A deploy that stops short usually stops for a reason it will tell you.

If the channel you are promoting into needs approvals, the ship still lands and the promote becomes a proposal: the CLI says how many confirmations it needs and where to confirm them. If the channel has a bake window, the promote lands and the fleet adopts when the window expires — the command exits successfully, because the hold is policy rather than a failure. And if no instance follows the channel yet, it says so instead of watching a URL that nobody serves, and names carlos instances create as the step that gives the version somewhere to run.

A watch that times out is a different situation. The version is published and the pointer has moved, so your app is either failing to start or failing its first request. Go to the logs:

carlos logs -app hello -since 10m

Full flag lists for deploy, ship and promote are in the CLI reference, and carlos deploy -h prints them at your terminal.