Install kitshn

Make a Cloudflare API token

Open the token page with the permissions filled in, then create the token. When a permission is missing later, the setup names it and prints this link.

Turn on Zero Trust

kitshn uses Cloudflare Access for every login. Open Zero Trust in the Cloudflare dashboard once and pick the free plan. The setup stops with the link when this step is missing.

Run the setup

Pick the admin address, for example kit.example.com on your domain:

curl -fsSL https://kit.yarden-zamir.com/install | \
  CLOUDFLARE_API_TOKEN=... \
  KITSHN_HOST=kit.example.com \
  KITSHN_OWNER_EMAILS=you@example.com \
  KITSHN_DEPLOY_OWNERS=your-github-name sh

It makes the Worker, its database, the R2 bucket, the Access applications and the Owner circle. Run it again at any time: it changes only what is not right, and prints each change.

Add your passkey and open the map

At the end, the setup prints the admin address and a link to register your passkey. Register it, then open https://kit.example.com. You log in with an email code and the passkey.

Add a recipe

Put kitshn.config.ts at the root of the repo. A static site:

import { defineApp } from "kitshn";

export default defineApp({
  static: { build: "npm ci && npm run build", output: "dist" },
  deploy: [
    { on: "push", branch: "main", name: "prod", startsIn: "Everyone" },
    { on: "pull_request", name: "pr-{pr}", ephemeral: true },
  ],
});

Use compose: { runsOn: ["docker"] } for a Compose app, or worker: { ... } for a Worker app. kitshn reads the recipe as data and never runs it, so it holds no loops and no function calls.

Add the workflow

Put this in .github/workflows/kitshn.yml. It is the same for every app:

on:
  push:
  pull_request:
    types: [opened, synchronize, reopened, closed]
  workflow_dispatch:
permissions:
  contents: read
  id-token: write
jobs:
  kitshn:
    uses: Yarden-zamir/kitshn/.github/workflows/kitshn2-deploy.yml@main
    with:
      server: https://kit.example.com
    secrets: inherit

The repo needs no secret. GitHub signs each run, and kitshn checks the signature.

Push, then Allow

The first push of a new repo waits. The map shows "1 repo waiting": click Allow, and the deploy starts. Every later push deploys at once.

Share it

The new card starts in the startsIn circle, or in the tray, private. Drag it into a circle to share it. Its address is <repo>.<your domain>.

Get a join command

On the map, click +, then Add a machine. kitshn shows a command with a one-time code that ends after 10 minutes.

Run it on the machine

curl -fsSL https://kit.example.com/join | sh -s -- <code> https://kit.example.com

It installs the daemon and its tunnel as services of your user. The machine needs no Node.js and opens no port.

Give it labels

In the machine panel, add the label deploy so that apps may run there, and labels such as docker that recipes ask for in runsOn.