Skip to Content

Quick start

From a checkout to an app running on your own server.

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.

You need

  • Bun 1.4.4, the version pinned in the repository.
  • macOS or Linux with a system keychain. Windows is not tested.
  • A Linux server you reach over SSH, on x86-64 or ARM64, with the GNU C library (glibc) 2.17 or newer, and Docker with its Compose plugin on it. It must reach github.com over HTTPS, to download the runner. Alpine and other systems with the musl C library are not supported yet. Supported servers and Installing the runner say the rest.
  • A folder with a compose.yaml for the app you want to run.

Zekno works today for one developer on one machine. Teammates arrive with the control plane, which is not written yet.

Build zekno

zekno is not packaged for installation yet, so you build it from the repository. It becomes one file.

git clone --branch main https://github.com/zekno-app/zekno
cd zekno && bun install
cd apps/cli && bun run compile   # dist/zekno: one file, for the system you are on

Put dist/zekno in a folder on your PATH. Build it from main: a zekno built from main installs the published runner release on your server (see Which runner it installs). To run zekno from the checkout instead, see Install.

Deploy

In your app's folder, run zekno deploy. With nothing set up yet, it sets up the three things it needs first: your key, a server and the app. It asks your name, where the server is and a name for it, and a name for the app.

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 in a folder with a compose.yaml and nothing set up. The name, the address and the codes are example values.

In those few lines:

  • Your key was made and stored in your system keychain. The team code identifies your team: a server checks it before it agrees to obey your team.
  • The runner was installed on the server over SSH, after its checksum matched the one your zekno holds, and the server was added to your signed team list. The server code identifies the server's key.
  • zekno.json was written in the folder, signed with your key, so it always deploys shop to prod-1.
  • The value the Compose file expects was asked for with nothing shown as you typed. It was sealed for that server only, and the deploy was signed with your key.
  • The runner checked the signature before it decrypted or started anything.

Run zekno deploy again after a change to deploy the next version. Each step of a first deploy is on zekno deploy. If something stops, zekno doctor checks your machine and the server and says what to do.

Look at it

Run zekno alone to open the app: your servers, what is running on each, and what you can do next. The window must be at least 80 columns by 24 lines.

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 once shop has been deployed twice: the server prod-1; shop at deploy 2, running; and what you can do from here. Every screen lists its keys on its last line.

q quits. Every screen and key is on The terminal app.

Next