Skip to Content

The 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.

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.

Run zekno alone at a terminal and a full-screen app opens. Everything the app does is also a single command, for scripts.

zekno with no arguments, at a terminal, opens a full-screen app. Without a terminal (piped, in a script, or with TERM=dumb) it prints the help and exits with status 2.

The window must be at least 80 columns by 24 lines. In a smaller one the app asks for a larger window, and comes back to the same screen when there is room. Each screen lists its keys on its last line. When you quit, the terminal is left as it was, also after an error.

ScreenOpens fromShows
HomeStart, when a team existsServers; the selected server's apps with deploy number, state and when; the selected app's details and actions; whether this folder is linked
Appenter on an appDeploy history; secrets by name and version; the selected deploy's details; a note when a secret is newer than the running deploy; for an app with a domain, a Domains box under the secrets
Deployd, or rSummary panel, with a domains row for a deploy with a domain; stage row, with a fifth stage for a health check; one live line; Docker's output on o and on failure
LogslTime, service, text; following or paused
First runStart, when no team existsThe logo, the three steps (your key, a server, a first deploy), the name question
Add a servera on Home, or step 2 of first runThe destination and name, each step as it completes, the team code and the server code with what each is for. Once done it stays, every step ticked and the server code shown, until enter goes to Home
Set a secrets, or before a deploy when values are missingThe names that are missing, the hidden prompt
Settingse on an appThis folder's zekno.app.json, one service at a time, in sections; on c, the Compose text it turns into. See The settings screen
Help?The app's keys, in groups. e and the keys of the settings screen are on their hint lines, not in help

A profile that does not verify opens an error screen with the reason instead of Home. Only q and ctrl-c work there.

The app: Home100 × 30

The full-screen app's Home. A header with the team, Ada's team, at team list version 2. Three panes: the servers, with prod-1 and its address; the apps on prod-1, with shop at deploy 2, running, deployed 2 minutes ago; and shop's details, with the keys to deploy this folder, roll back to deploy 1, read the logs and set secrets. The keys of the screen are on the last line.

Home: the servers pane with prod-1 and its address; the apps on prod-1, with shop at deploy 2 and running; and shop's details and actions. The folder is linked to shop by zekno.json.
The app: shop100 × 30

The full-screen app's screen for shop on prod-1, which is running. Its deploys, newest first, each with its number, result and time, the latest selected with its details; and its secrets by name and version. The keys of the screen are on the last line.

The App screen for shop, opened with enter on it: its two deploys, the latest selected with its details, and its secrets by name and version, never a value.

For an app with a domain, the App screen has a Domains box under Secrets: each domain, and under it its state after a mark, as zekno domain gives them, without the detail. At its foot, dim: Checked from this machine. and e settings to change them.; below 100 columns it has no foot. The box only shows, and takes no keys. It is read in the background when the screen opens and after a deploy of the app, over SSH in batch mode only, and not while SSH needs an answer for that server. It is there when this folder deploys the app from a settings file, linked to it or to nothing, and that file or the app's last deploy from this machine has a domain. Otherwise there is no box, and nothing more is asked of the server.

Keys

KeyWhereDoes
↑ ↓Lists, logs, settingsMove the selection, or scroll
← →, tabHome, App, SettingsMove between panes. On Settings, tab shows the next service
enterLists, questionsOpen, or confirm. On a secret, set its new value. On Logs after the connection dropped, connect again. On Home, on a server marked ! (SSH needs an answer), connect to it so SSH can ask. On Add a server once it is done, go to Home with the new server selected. On Settings, change the selected setting
escEverywhere but HomeGo back. On Deploy, the deploy carries on. At the hidden prompt before a deploy, back to the list of missing values; on that list, the question "deploy without them?" On Settings while a change is open, close it and write nothing
dHome, App, SettingsDeploy this folder (see Deploying from the app)
eAppOpen the app's settings, from this folder's zekno.app.json
cSettingsShow the Compose text the settings turn into, or the settings again
rHome, AppRoll back: on App to the selected deploy, on Home to the one before the latest
lHome, AppLogs
sHome, AppSet a secret
xApp, secrets paneRemove the selected secret, after a confirm
aHomeAdd a server
uHome, on a server marked ! older runnerUpdate the runner, after a confirm
oDeploy, Add a serverShow or hide the full output
fLogsPause or resume following
/LogsFilter by text; esc clears it
1 to 9LogsShow one service; 0 shows all
?Everywhere but the profile error screenHelp for this screen
qEverywhere but a questionQuit. Waits for a deploy in progress
ctrl-cEverywhereAs q. In the hidden prompt it cancels the prompt only

A key that does nothing on the current screen is ignored. While a text question is open, letter keys type into it.

Questions

QuestionAskedAnswers
Remove NAME?x on a secretenter removes it, esc cancels
The runner on <server> is out of dateuu updates now, esc leaves it for later
<member> linked this folder to <app> on <server>The app opens where a teammate's signed zekno.json was not used here before. A file in a folder above is named with that folder and its Compose file: <member> linked <folder> to <app> on <server>, with <folder>/<compose>y uses it here, n or esc not now
Remember this folder?d in a folder with no zekno.jsonenter writes zekno.json, signed by you and naming the file it deploys (compose.yaml or zekno.app.json), and deploys, n deploys without it, esc cancels
This folder is linked to <app> on <server>d in a linked folder with another app selectedy deploys the folder to the selected app, n or esc does not deploy
Deploy <app> to <server> without NAME?esc on the list of missing valuesy deploys, n or esc does not deploy
Write this to zekno.app.json? Nothing is deployed until you deploy.A new value on the settings screeny writes it, n, enter or esc keeps the value and writes nothing

What is running, and keeping in touch with servers

  • Home and the App screen show each app as running, stopped, partly running or unknown, by a word and a symbol as well as a colour. An app is running when every service runs, stopped when none does, and partly running otherwise.
  • State is read when a screen opens and every 5 seconds while Home or App is showing: Home reads every server, App its own. Nothing is read while a question is open, below 80 by 24, or while the app is quitting.
  • When the app starts, it opens one session to each server: one SSH connection to the runner, kept open while the app runs. That is the moment SSH may ask for a password. Each read sends its requests over that session, so a read adds no SSH login. One read per server at a time.
  • A read with no answer within 20 seconds, or a session that ends, closes that session. The server is then shown as not reached, with the reason, and its apps' state as unknown. Its apps keep the deploy numbers your machine has.
  • A server whose session was lost is connected to again in the background, at most once every 30 seconds, in SSH's batch mode only: it never asks for a password and never takes over the terminal.
  • Where SSH would have had to ask (a password, a key passphrase, a host key) and was not answered, the server is marked ! instead of its dot, with "needs an answer" under its name, and its apps' state is unknown. It is not tried in the background again until you connect to it on purpose: enter on it in the servers pane (the hints say enter connect), or start the app, deploy, roll back, open logs, update or add. A server that refuses the connection, does not answer in time or does not resolve is shown as not reached (✖).
  • enter connect tries SSH's batch mode, then hands the terminal over so SSH can ask, checks that it is the server you connected, and keeps the session for the reads that follow. If you cancel at SSH's question, the mark stays.
  • Deploys, rollbacks, secrets and logs use connections of their own, never the kept session.
  • After a server is added from the app, the session it was added over is kept, so SSH does not ask a second time.
  • A runner that does not report its version has no sessions. It is read when the app starts and after u, never in the background.
  • Every kept session is closed when the app closes, on q, an error or a signal.
  • If SSH has to ask for a password or a host key, the app first tries SSH's batch mode, then hands the terminal over so you can answer on the normal screen, and takes it back once the connection is up.

Deploying from the app

  • A folder linked by a zekno.json signed by your team and in use on your machine deploys at once to its own app on its own server, and on its own server with no apps. With another app selected, on its own server or another, d first asks: "This folder is linked to web on dev. You selected billing. Deploy this folder to billing? It replaces what billing runs now." Only y deploys the folder's file to the selected app; n or esc ends with "Nothing was deployed.", and enter does nothing. Nothing is read from the keychain, signed or sent before y, and zekno.json is not changed. On another server with no apps, d says so and deploys nothing. One exception: on its own server, a linked app that has never been deployed there has no row to select yet, so d deploys it as its first deploy whichever row is marked. No other app is replaced.
  • d deploys the file zekno deploy would: the one a linked folder's zekno.json names, which may be zekno.app.json, or in a folder that is not linked the one of compose.yaml and zekno.app.json that is there. With both there and no zekno.json, d deploys nothing and says This folder has zekno.app.json and compose.yaml. Run zekno link -f <file> here to say which. Neither is ever picked over the other without you saying so.
  • A folder with no zekno.json deploys its file to the selected app. Before the first deploy, the app asks whether to remember the folder; yes writes zekno.json naming that file, signed with your key, and records it as used here. With no app selected, it points you to zekno link.
  • A folder whose zekno.json is not signed by your team deploys nothing, and Home says why. One signed by your team that was not used here before is asked about when the app opens; until you say yes, d deploys nothing and says so.
  • The file is read once, when d is pressed. A settings file is turned into its Compose text then, and a fault in it is said on the status line before any question; nothing is deployed. The names listed and the text signed come from that one read.
  • Before a deploy, names the Compose text expects that have no secret are listed, at most 64. Each can be set with the hidden prompt, or the deploy can go ahead without them. At the prompt esc returns to the list and signs nothing. On the list esc asks before deploying without them; "no" ends with "Nothing was deployed.".
  • esc during a deploy returns to the screen before; the result arrives there as a line. q waits for the deploy to finish, then closes.
  • The deploy screen shows a summary panel, a row of stages (checked, signed, sent, starting, then started or failed) and one live line. Docker's full output is shown on o, and on a failed start.
  • A deploy with a domain is checked as zekno deploy checks it (see The check before a deploy). Each new domain that points to the server has its line above the panel, and the panel has a domains row, one domain a row. A stop before signing shows the panel with ✖ Checked and the sentence. While the deploy waits for HTTPS, the live line is the wait for the certificate; once it ended, the address live, or not ready yet, is under the result. The app cannot skip the DNS check: only zekno deploy --skip-dns-check does.
  • A deploy with a health check has a fifth stage, healthy, after started (see Health checks). While a service with a path is waited for, the live line says waiting for web to answer GET /health, without the seconds: the header counts the time.

Logs in the app

The logs screen follows an app's logs over a connection of its own. It keeps the last 2000 lines in memory and writes nothing to disk. It says where they come from: "Read straight from your server over SSH. Nothing passes through Zekno." When the connection drops, it says so, and enter connects again.