The project file
The project file zekno.json, zekno link, and linking a folder.
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.
{
"app": "api",
"server": "prod",
"compose": "compose.yaml",
"signed": { "payloadType": "zekno.link.v1", "payload": "...", "signature": { "keyId": "...", "sig": "..." } }
}It saves typing --app, --server and -f in a project folder. It holds
three names and your team's signature of them, nothing else: no secret and no
key (the signature and the key id are public), so committing it gives
nothing away. Its signature vouches for the names (which app, which server,
which file), not for what the file says. Whatever is checked out in a linked
folder is what zekno deploy deploys there, so read a branch, such as a pull
request's, before you deploy it.
| Field | Rule |
|---|---|
app | An app name: lowercase letters, digits and hyphens |
server | A server name, same rule. It must be a server connected on your machine when used |
compose | The file the folder deploys: a Compose file, or zekno.app.json. A relative path inside the folder that holds zekno.json. No .., not absolute. Without -f, zekno link writes the one of compose.yaml and zekno.app.json that is there |
signed | The signature zekno link adds: a member of your team signed this app, server and file |
When compose names a file called zekno.app.json, a deploy reads it as
settings and signs the Compose text they turn into, so the settings are signed
at each deploy, as a Compose file is. Every member of your team who deploys
such a folder needs this zekno or later: an older zekno reads the settings
file as a Compose file and signs it as it is, the runner accepts that deploy,
and Compose refuses the text on the server, so the app does not start.
- An unknown field is an error, and so is a field written twice.
- It is looked for in the current folder, then each folder above it, stopping at your home folder or the filesystem root. A folder above your home folder is never read.
- Only a regular file named exactly
zekno.json, of at most 4096 bytes, that belongs to you is used. A symbolic link, a pipe or another user's file is an error that names it. - It is written only by
zekno linkor a "yes" in the app, signed with your key, never over an existing one without--force, as a whole file with mode 644.
zekno link
Writes zekno.json in the current folder, signs it with your key, and
records it as used on your machine.
-
An app or server not given is taken from a
zekno.jsonthat already applies to the folder, only when it is signed by your team and in use here. From any other nothing is taken: it stops with exit status 2 and says why. -
-fnames the file the folder deploys, a Compose file orzekno.app.json, and must be a file inside the folder. A newzekno.jsonwritten without-fnames the one ofcompose.yamlandzekno.app.jsonthat is in the folder. With both there it writes nothing and stops with exit status 2, at a terminal too, before it asks anything:This folder has zekno.app.json and compose.yaml. Say which with -f <file>.With neither,No Compose file at <folder>/compose.yaml. Point to one with `-f <file>`. -
It does not overwrite a
zekno.jsonwithout--force. With--forceand names, it replaces any file with one signed by you. -
With no
--app,--serveror-f, azekno.jsonsigned by your team that already applies (in this folder or one above) is checked as one being written would be, and recorded as used here, not rewritten. Recording it is the same decision as the question every command asks the first time it meets a teammate's file, sozekno linkasks it too, and onlyyrecords it:Accepted zekno.json: <app> on <server>, file <compose>.No stops with "Nothing was done." and exit status 1. With no terminal it stops with exit status 2 unless you add--yes:There is no terminal to ask on. Ada linked ~/code/shop to api on prod. Add
--yesto use it here.A file already in use here is left as it is:
Already in use: zekno.json, <app> on <server>, file <compose>.A file not signed by your team is refused. Names given that are exactly those of a signedzekno.jsonin this folder are asked about and recorded the same way.
zekno link --app api --server prodLinking a folder
Run zekno link --app <app> --server <server> in the folder, or answer yes
to "Remember this folder?" in the app. Commit the zekno.json it writes.
From then on, in that folder and the folders below it, zekno deploy,
rollback, status, logs and secret need no --app or --server, and
the app opens on that app.
Two things must both be true before zekno uses a zekno.json:
-
Someone in your team wrote it. Its signature is checked against your verified team list, as it is now. A file with no signature, one from another team, one signed by someone since removed from the team, one edited by hand after it was signed, or one signed for a server of another name is not signed by your team. It is refused outright and never offered:
zekno.json in ~/code/shop is not signed by your team, so zekno does not use it. It names api on prod. To link this folder yourself, run
zekno link --app <name> --server <name> --force. To leave the file aside, give --app and --server.With no terminal a command stops with exit status 2. At a terminal it names the file with its first two sentences, leaves it aside, and asks for the server and the app as if it were not there;
zekno linkwithout--forcestops instead, since writing would replace the file. The app shows the first two sentences on Home, selects nothing, andddeploys nothing. -
You used it in this folder on your machine before, or you say yes once. A signature proves who wrote a file, not where it is: anyone who can read a repository can copy its
zekno.jsoninto another folder beside another Compose file. So the first time a teammate's file is met in a folder, zekno shows what it names and asks once. At a terminal:Ada linked this folder to api on prod. Use it here?Onlyygoes on; anything else stops with "Nothing was done.". A file in a folder above is named with that folder and the Compose file a yes deploys:Ada linked ~/Downloads to api on prod, with ~/Downloads/compose.yaml. Use it here?In this folder, the file a yes deploys is named when it is notcompose.yaml:Ada linked this folder to api on prod, with deploy/zekno.app.json. Use it here?(the app's own question names no file). When--appor--serversends the command elsewhere than the file names, the question says both:Ada linked this folder to api on dev. This command uses api on prod. Use it here?A key typed before the question is drawn, such as while the keychain asks, is thrown away: only aytyped at the question answers it.zekno linkasks the same question. The app asks when it opens, withy use itandn not now. With no terminal the command stops with exit status 2:Ada linked ~/code/shop to api on prod, and it has not been used in this folder on this machine. To use it, run
zekno linkthere once and answer its question, orzekno link --yesfrom a script. To leave it aside, give --app and --server.
What you have used is recorded in links.json in the profile folder: the
real path of each file and the SHA-256 of its bytes. Any change to its bytes,
such as a teammate's new link arriving with a git pull, is asked about once
more. Given both --app and --server, a command leaves the file aside
unless it is in use here, and never asks; a file that cannot be read (a link,
another user's file, not valid JSON) then counts as no zekno.json.
links.json is not signed, on purpose: someone who can write your profile
folder and also plant a project folder gains nothing from it they do not have
already, and an entry alone never makes a file count.
Its file goes with its app. With --app naming another app, the file is
-f, or the one of compose.yaml and zekno.app.json in the current folder,
as without a project file.