Skip to Content

Deploying

zekno deploy, rollback, status and logs.

Pre-alpha and unaudited

The command-line tool, the runner and the core library have had internal reviews only. Do not use them for anything you could not afford to lose, and do not rely on them in production before an external audit.

zekno deploy

Signs a deploy with the next deploy number, and sends it to the runner over one connection. What it deploys is a Compose file, or an app's settings in zekno.app.json turned into Compose text on your machine (see zekno settings). The first of these that applies decides which file:

  1. -f <file>, when given. It may be anywhere. A file named exactly zekno.app.json is read as settings, any other as a Compose file.

  2. Otherwise the file a zekno.json signed by your team and in use here names, when the app is the one it names. It may be zekno.app.json.

  3. Otherwise the one of compose.yaml and zekno.app.json in the current folder, when only one of them is there.

  4. Both are there, and nothing above says which. At a terminal, zekno deploy asks:

    ? Deploy from which file?
      ❯ zekno.app.json  your settings
        compose.yaml    a Compose file written by hand
      ↑↓ move   enter choose   esc leave

    Enter leaves ✔ From zekno.app.json (or compose.yaml) and goes on with that file. With no terminal it deploys nothing, connects to nothing, and stops with exit status 2: This folder has zekno.app.json and compose.yaml. Say which with -f <file>.

Neither file is ever picked over the other without you saying so. A name counts as there even when it is a symbolic link that leads nowhere; the file's reader then says what is wrong with it. With neither file and nothing above, the deploy stops with No Compose file at <folder>/compose.yaml. Point to one with `-f <file>`.

Except with -f, the file must stay inside its folder: a symbolic link out of it is refused. Every file is read once, from one open file, and must be a regular file: at most 256 KiB for a Compose file, 64 KiB for a settings file. A named pipe is refused, not waited on. Do not put secrets in the Compose file itself: it is stored and sent as written. A settings file cannot hold a secret's value.

A settings file is read and checked whole. A fault in it, or a setting this version does not have, stops the deploy with its sentence and exit status 1, before anything is connected, signed or sent. From a settings file, the text that is signed, sent and recorded is its Compose text, byte for byte the text zekno settings compose prints. Rollback, status and logs work on it as on any deploy. A service removed from the settings is stopped at the next deploy. A volume removed from them keeps its data (see Volumes).

At a terminal, the summary panel of a deploy from settings has one more row, after server: the file, then its services, dim.

app      demo
server   prod deploy@203.0.113.7
from     zekno.app.json  2 services: web, worker

A deploy from a Compose file draws the panel as before. Plain output and --json are the same for both.

Exit status 1 when the runner accepted the deploy but the app did not start. The deploy number is used either way. A deploy in the new deploy format that the runner refuses uses no number (see The deploy it is made after).

zekno deploy --app api --server prod -f compose.yaml

At a terminal, zekno deploy run in a project folder first sets up what is missing, in this order. Each thing is kept as soon as it is made. With both files in the folder, "Deploy from which file?" is asked first, after the question about a teammate's zekno.json when there is one. A fault in the settings file is said next, before any other question.

  1. Your key. It asks your name, creates the key in the system keychain as zekno init does, and shows the team code.
  2. A server. It asks where the server is (user@host) and a name for it, installs the runner as zekno server add installs it, and shows the server code. With one server it uses that one and says so. With several it asks which.
  3. The app. It offers the apps on that server, and + a new app with the folder's name filled in. When it asked for the server or the app, it asks whether to remember this folder: yes writes a signed zekno.json naming the file deployed, as zekno link does.
  4. The values the Compose file or the settings expect that have no secret yet. Each is asked with nothing shown as you type. Esc skips one, and the next run asks for it again.
  5. Then the deploy.
A first deploy, from nothingzekno deploy

zekno deploy in a folder with a Compose file and nothing set up. It asks for your name and makes your key, with its team code; asks where the server is and a name for it, connects over SSH, finds Docker, installs the runner and adds the server, with its server code; asks a name for the app and whether to remember the folder; asks for the one value the Compose file expects without showing it; then deploys, and shop is live on prod-1.

A first deploy from nothing: your key, then the server prod-1 with the runner installed, then the app shop, one value asked for, and the deploy.

Esc or Ctrl-C leaves any question. What was made before it is kept, and running zekno deploy again carries on from there. A detail given by a flag or by a linked folder is never asked for. With no terminal, zekno deploy asks nothing and stops as before.

The deploy it is made after

With a runner that speaks protocol 3 (see An older or a newer runner), zekno deploy signs in the new deploy format, deploy format 2. On the deploy's own connection it reads the app's last deploy number from the runner, and signs a deploy made after that one, numbered one above it. The runner takes it only while that number is still its last for the app. So a deploy that another deploy of the app overtook never runs, even one held back and delivered later. This machine keeps no number of its own for it, and sets no limit on how far ahead the runner's number may be.

A deploy in the new format that the runner refuses uses no number and runs nothing: the next deploy is made after the same one. When another deploy of the app reached the runner first, zekno reads the runner again on the same connection and says which one, under the stage row at ✖ Starting:

Another deploy of <app> reached <server> first, as deploy <n>. Nothing of this one ran. Run zekno deploy again to deploy on top of it.

When this machine also signed a deploy with that number whose answer never came, here or in another terminal, it cannot tell which of the two ran:

<server> holds deploy <n> of <app>, and this machine signed a deploy <n> whose answer never came. zekno cannot tell which of the two ran. Run zekno deploy again to settle it.

When the runner cannot be read again, the sentence names no deploy: Another deploy of this app reached the runner first. Nothing of this one ran. Run zekno deploy again to deploy on top of it. With no terminal, or with --json, each of these is one line on standard error, and nothing is printed on standard output. On the app's deploy screen it is the result line, and Number <n> is used, so the next deploy will be <n+1>. is not shown after a deploy in the new format that was refused or got no answer.

A deploy zekno signs carries no expiry. It is kept in this machine's deploy history and sent only on the connection it was signed for.

When the runner refuses

Each reason the runner may refuse a deploy in the new format with is said in one sentence:

The runner's reasonzekno says
replayedOne of the sentences above
sequence_jumpThis deploy was made after a deploy the runner does not hold. Nothing of it ran. Run zekno status to see what the runner holds.
secrets_mismatchThe deploy does not account for every secret the runner holds for this app. Nothing of it ran. Run zekno deploy again.
secret_missingThe runner does not hold a secret this deploy lists, and it was not sent with it. Nothing of it ran. Run zekno deploy again.
untrusted_secretA secret of this app was set by someone who is no longer in the team. Nothing of this deploy ran. Set it again with zekno secret set, or remove it with zekno secret rm.
expiredThe time this deploy had to run had passed by the server's clock. Nothing of it ran. Deploy again, and check the server's clock if it says so again.
unsupported_versionThe runner on that server does not carry out everything this deploy asks for. Nothing of it ran. Run zekno status to compare its version with this zekno's.
malformed, wrong_payload_typeThe runner could not read this deploy. Nothing of it ran. Run zekno status to compare its version with this zekno's.

The last two rows are said for a deploy in either format. For a deploy in the older format, replayed, sequence_jump and secrets_mismatch keep the sentences they had. sequence_jump in the new format means the runner holds a lower number than it said, as a runner folder restored from a backup would, and that is not supported (see the runner page). What the secrets rows mean is on Secrets.

An older or a newer runner

zekno asks the runner its version first, on the deploy's own connection, and signs in the format the runner speaks:

The runnerThe deploy
Speaks protocol 3Signed in the new format
Speaks an older protocol, as every released runner does, 0.1.0 includedSigned in the older format, as before
From before sessions, so it reports no versionSigned in the older format, as before
Speaks a newer protocol than this zeknoNot signed

No runner release speaks protocol 3 yet. A zekno built from the repository still installs runner 0.1.0, so on a server with a released runner every deploy is signed in the older format, as before: numbered one above the runner's number and the highest this machine signed, with every secret sent each time. A runner built from the repository speaks protocol 3.

When a runner of an older protocol reports a version older than the one this zekno carries, the deploy says so once it is signed, and goes on. At a terminal the warning is drawn above the deploy's panel, on the app's deploy screen it is a warning notice, and with no terminal it is a line on standard error, never in --json's object:

The runner on <server> is version <version>, older than this zekno's <carried>, so this deploy was signed in the older format. Run `zekno server update <server>` to bring it to <carried>.

<carried> is the runner release this zekno carries. A runner of that same version, such as runner 0.1.0 with a zekno that carries 0.1.0, gets the older format and no warning.

A runner that speaks a newer protocol than this zekno stops zekno deploy and zekno rollback before anything is signed, and nothing goes into the deploy history:

The runner on <server> is version <version>, newer than this zekno's <carried>, and speaks a newer protocol. Update zekno to deploy to <server>. Nothing was signed.

zekno rollback

Deploys an earlier service definition again, under the next number, with the current secrets. Only deploys your machine signed and the runner answered for count, in either format. Without --to, it returns to the one before the latest.

In the new deploy format a rollback is a new deploy made after the current one, like any other: it names the app's last number and is signed one above it, even when it returns to a deploy made in the older format. When another deploy reached the server first, its sentence ends Run zekno rollback again to deploy on top of it. Against an older or a newer runner it does what zekno deploy does.

zekno rollback --app api --server prod --to 3

zekno status

Reads what a server holds: its team list version, each app's last deploy and whether it is running, and each secret's version. Never a value. When the runner is older or newer than the one this zekno carries, a warning says so, and what works until they match: an older runner is brought up to date with zekno server update, and for a newer one you update zekno. Deploys still work, unless the newer runner speaks a newer protocol; then you are told to update zekno first, and zekno deploy stops before signing (see An older or a newer runner).

zekno status --server prod
What is runningzekno status

zekno status, which uses prod-1 as the only server: prod-1 is reachable and holds team list version 2, shop is at deploy 1 and running, and shop's secret DATABASE_URL is at version 1.

zekno status with one server: prod-1 is reachable at team list v2, shop is at deploy 1 and running, and its one secret is at version 1.

zekno logs

Prints an app's logs, read straight from its server. --tail <n> is how many earlier lines Docker sends first: 0 to 1000, 200 by default. It follows until interrupted, or until Docker's log command or the connection ends. --no-follow prints the lines Docker has and ends. Ctrl-C, or a reader that closes the pipe (zekno logs | head -1), stops the reading on the server and ends the command quietly with status 0. It needs a runner that reports its version, as every released runner does, and an app the server has a deploy of. Nothing is written to disk.

zekno logs --app api --server prod --tail 50 --no-follow