Skip to Content

Introduction

What Zekno is, what works today and its limits, how a deploy happens today, and the hosted service that is planned.

Pre-alpha

Nothing here is ready for production use, and the security design has not been independently audited. The command-line tool and the server runner work today, for one developer, deploying directly over SSH. The hosted service is not built yet; these docs describe the design it will follow.

What Zekno is

Zekno gives a team the convenience of a managed platform (one command to deploy, teammates with roles, deploy history) on servers they own, starting with Hetzner and Docker Compose.

It is built so that a full compromise of the Zekno service yields no customer secrets and no ability to run code on customer servers.

PropertyWhat it means
Client-side encryptionSecrets are encrypted on your machine. The hosted service only ever stores ciphertext.
Signed deploysEvery deploy is signed on your machine. Your servers refuse anything your team didn't sign.
Auditable client codeEverything that runs on your side is in the public repository.
No runtime dependencyYour servers don't need Zekno to keep your apps running.

To try it, follow the Quick start: from a checkout to an app running on your own server.

What works today

zekno, the command-line tool, and the runner on your server work today, for one developer. With them you can:

  • deploy a Docker Compose app to your own server (Deploying)
  • keep its secrets sealed on your machine (Secrets)
  • describe the app by settings instead of a Compose file (App settings)
  • add a database from a template (Templates)
  • see what is running, read its logs and roll back (The terminal app, Deploying)
  • give the app a domain, served over HTTPS with a certificate the server obtains itself, and make a deploy wait until the app is healthy (Domains and HTTPS, Health checks). Both need runner 0.1.1, which is not published yet.
PartStatus
Website (apps/web)Landing page and these docs
Core library (packages/core): encryption, signing, team lists, message formatsFirst version built; internal review only
Command-line tool (apps/cli)Second version built: a full-screen terminal app and single commands for scripts, running state and logs read from your server, and a project file. One developer, deploying directly over SSH. It installs on a server the runner release its build carries, checked against a checksum it holds. The first runner release, 0.1.0, is published. Internal reviews only. See Commands
Server runner (apps/runner)Second version built: verifies, decrypts, starts Docker Compose, and reports running state and logs without changing anything. One connection per command. Built for Linux on x86-64 and ARM64 with glibc 2.17 or newer. A runner built from the repository also serves an app's domains over HTTPS, through a proxy it starts on the server, and waits for health checks; no release does yet. Internal reviews only. See Server runner
Control planeNot built yet. When built, hosted by Zekno, closed source

A deploy today

  1. Seal and sign. On your machine, zekno seals each secret for the server it goes to, and signs the deploy with your team's key.
  2. Send. It sends the sealed, signed deploy to the runner on your server, over SSH. No Zekno service is involved.
  3. Verify and decrypt. The runner checks the signature first, and refuses a deploy your team did not sign. Only then does it decrypt the secrets, with the server's own key.
  4. Run. The runner starts your containers with Docker Compose.

Who holds which key, and what that does and does not protect against, is on Security model.

The hosted service, planned

The hosted service, the control plane, is not built. In the design, it sits between your machine and your servers and holds nothing it can open: it stores the sealed, signed deploy, and your server's runner pulls it over an outbound connection. Teammates with roles and deploy history arrive with it. If it is unavailable, zekno deploys to the runner directly, over SSH, as it does today. The steps of that design are on Security model.

Status and limits

  • One developer on one machine. Teammates arrive with the control plane, which is not written yet.
  • SSH is the route. zekno talks to the runner directly, over SSH. No Zekno service is involved.
  • Only zekno version and zekno doctor reach the network on their own: each asks GitHub once for the newest release, and sends nothing about you. For an app with a domain, zekno deploy, zekno domain and the full-screen app also look the domain up with your system's resolver and ask it over HTTPS, as a visitor would. Nothing of it goes to Zekno.
  • State and logs come from your server. Whether an app is running, and its logs, are read from the runner over SSH when you look. They never pass through Zekno, and your machine keeps none of it.
  • The runner comes from a release. zekno server add installs on a server the one runner version your build of zekno carries, and only when it matches the checksum that build holds. A zekno built from main installs a prod release, such as 0.1.0; one built from dev installs a development release, such as 0.1.0-dev.1. See Installing the runner.
  • The first runner release is 0.1.0. A zekno built from main holds its checksums and installs it on a server by itself. Between a release being started and its second build, a zekno built from that branch holds no checksums and says it has no published runner to install.
  • Docker's messages are shown as they are. An error from Docker can repeat a value that was filled in from a secret.
  • App settings cover an image that is already built. This version cannot build an image from source, run a command before a deploy, or run several copies of a service. A zekno.app.json that sets one of them is refused with a sentence that names it. A Compose file written by hand can do what Compose does.
  • Domains come from a settings file, with certificates from Let's Encrypt only. The server's ports 80 and 443 must be free, and the server holds the TLS keys of its domains. zekno never changes DNS: it checks it from your machine. A deploy still replaces the app's containers, so requests during it can fail. See Domains and HTTPS.
  • A published port is open to whoever can reach the server. It is published on every address of the server, as Compose does, and Docker's published ports can pass a host firewall such as ufw. Zekno does not manage the server's firewall.
  • "Changed, not deployed" knows only your machine's deploys. A teammate's later deploy from another machine is not seen.
  • Made for macOS and Linux with a system keychain. Windows is not tested.

The internal security reviews, which say what was checked and what was not, are in the specs folder of the repository.

Where to go next