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:
-
-f <file>, when given. It may be anywhere. A file named exactlyzekno.app.jsonis read as settings, any other as a Compose file. -
Otherwise the file a
zekno.jsonsigned by your team and in use here names, when the app is the one it names. It may bezekno.app.json. -
Otherwise the one of
compose.yamlandzekno.app.jsonin the current folder, when only one of them is there. -
Both are there, and nothing above says which. At a terminal,
zekno deployasks:? Deploy from which file? ❯ zekno.app.json your settings compose.yaml a Compose file written by hand ↑↓ move enter choose esc leaveEnter leaves
✔ From zekno.app.json(orcompose.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, workerA 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.yamlAt 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.
- Your key. It asks your name, creates the key in the system keychain as
zekno initdoes, and shows the team code. - A server. It asks where the server is (
user@host) and a name for it, installs the runner aszekno server addinstalls it, and shows the server code. With one server it uses that one and says so. With several it asks which. - The app. It offers the apps on that server, and
+ a new appwith 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 signedzekno.jsonnaming the file deployed, aszekno linkdoes. - 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.
- Then the 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.
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 reason | zekno says |
|---|---|
replayed | One of the sentences above |
sequence_jump | This 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_mismatch | The deploy does not account for every secret the runner holds for this app. Nothing of it ran. Run zekno deploy again. |
secret_missing | The 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_secret | A 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. |
expired | The 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_version | The 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_type | The 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 runner | The deploy |
|---|---|
| Speaks protocol 3 | Signed in the new format |
| Speaks an older protocol, as every released runner does, 0.1.0 included | Signed in the older format, as before |
| From before sessions, so it reports no version | Signed in the older format, as before |
Speaks a newer protocol than this zekno | Not 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 3zekno 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 prodzekno 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 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-followThe terminal app
The full-screen app zekno opens at a terminal, with its screens, keys and questions, how it keeps in touch with servers, deploying from it, and logs.
Your key and servers
Your key with zekno init, your servers with zekno server add, update and ls, and how the runner is installed and trusted.