Kitten

Reference sections

To deploy your app as a service, you use the deploy command from a regular account (not root) under Linux:

kitten deploy <httpsGitCloneURL>

For example, the following will create and run a production server of the Persisted Kitten Chat example, as hosted on my personal Codeberg account at my hostname.

kitten deploy https://codeberg.org/aral/persisted-kitten-chat

As Kitten runs in an unprivileged account, systemd must let services for that account remain running when you sign out of your server (otherwise your Kitten server will stop when you exit your ssh session or log out of your server). The kitten deploy command enables this (lingering) for the account for you.

If it can’t, it shows a warning with the command to run yourself. e.g., If you installed Kitten under a Linux account called kitten:

sudo loginctl enable-linger kitten

Note that the name you use in the enable-linger command is the name of the Linux account, not the Kitten process/systemd unit file name. If you deployed a Kitten app from a Linux account called aral, you would instead type sudo loginctl enable-linger aral.

Kitten will not automatically create an alias for www for you, pass the --aliases=www.<hostname> option (or the shorthand, --aliases=www) if you want that. You can, of course, also list any other subdomains other that www that you want Kitten to serve your site/app on in addition to the main domain.

If your app uses node modules and a package-lock.json exists, Kitten runs npm ci on your project and on any app modules your project might have. Without a package lock file, Kitten runs npm install instead.

How your deployed app is updated depends on who it is for.

When Kitten starts up, it runs npm ci in your app’s folder and in each of its app modules where the packages in the folder’s package-lock.json differ from the record npm keeps at node_modules/.package-lock.json (or where there is no node_modules folder). If a folder has no package-lock.json, Kitten runs npm install there instead.

You can set up a webhook on your remote Git source code repository that updates the site whenever you push to its tracked branch.

You can find your webhook URL and webhook secret on the App Settings page of your Kitten site (/đŸ±/settings/app/).

If your domain changes (i.e., if you point a new domain to your site using Kitten’s Settings panel), remember to update your webhook at your git host to use your new Webhook URL.

Your Kitten site expects the webhook secret in either the Authorization header or in the body of a POST request in a field called secret (the body should be application/x-www-form-urlencoded).

e.g., Instructions for Codeberg:

  1. From your project’s repository, follow the Settings link.
  2. In the Settings menu, select Webhooks.
  3. Press the Add webhook button.
  4. From the button’s pop-up menu, select Forgejo.
  5. Enter the Webhook URL from below into the Target URL field.
  6. Leave the HTTP method set to POST.
  7. Set the POST content type to application/x-www-form-urlencoded.
  8. Leave the Secret field empty.
  9. Set Trigger on to Push events
  10. Set Branch filter to the branch Kitten tracks: release if your repository has one, your default branch otherwise (the App Settings page shows which)
  11. Enter the Webhook secret from below into the Authorization header field.
  12. Leave the Active checkbox checked.
  13. Press the Add webhook button.

Once the webhook has been added, your site updates whenever you push to the tracked branch.

Each push runs the same update as Kitten’s automatic updates. Kitten installs your app’s dependencies before switching to the new commit and installs the newest Kitten release for the API version declared by the commit (if that’s a newer release than the one you’re running), and rolls both back if the new version fails to start or if its home page responds with a server error. (If the package.json file in the commit doesn’t declare an API version, Kitten installs the newest release for the API version you’re running.) An update that fails is not retried (see Versioning). Fix the issue and push again to trigger another update attempt. You can see the outcome of each update in the update history on the Kitten Settings page.

A webhook also works for an app that declares the engines.kitten field (see Versioning, below). It updates your own server as soon as you push (e.g., for a security fix), while other people’s servers install the same update at their next automatic check.

This is a feature that will be useful to developers who are deploying their own sites and apps for their own use as opposed to developers making apps for use by everyday people who use technology as an everyday thing. For the latter use case, please see Versioning, below.

To try out a Kitten app from its git repository without deploying it, use the kitten run command.

A Kitten app declares the Kitten API version it supports in its package.json file:

{
  "engines": {
    "kitten": "1"
  }
}

The Kitten API version is a whole number that’s incremented when a Kitten release contains one or more breaking changes.

Before you add or update the engines.kitten field on an existing app, update Kitten locally on your development machine and run the kitten check command. This will report any issues it finds in your codebase that are incompatible with the latest version and suggest fixes (and sometimes it can even fix them for you). Once your app increments its API version, deployed instances of it are automatically upgraded to the newest Kitten release of that version at the next automatic upgrade check.

A deployed Kitten app pulls in changes from one of two branches in a publicly-readable remote git repository:

Any new commit on the tracked branch is a candidate for installation and upgrade.

For Small Web apps you expect other people to deploy to their own servers, we recommend that you either use a release branch or work in feature branches and only merge into main when you want to make a release.

Here’s how you’d release a new version of your app when using a release branch:

git push origin main:release

If your app doesn’t declare an engines.kitten value, deployed apps stay on the API version of the Kitten version they’re deployed with.

To upgrade such an app, you can:

Kitten itself still updates automatically on these servers (to the newest release within its API version). To stop it from doing so, set Check for updates to never on the Kitten Settings page. (The four ways of updating listed above still work when you do.)

An app’s version comprises a dash-separated string listing its API version, the first six characters of its commit, and the commit’s date in UTC. e.g. 1-3f9a2c-20261007101500. Apps that don’t declare the engines.kitten field do not have an API version.

Every six hours (the interval is on the Kitten Settings page), a production server asks the distribution server for releases and its app’s repository for the head of the tracked branch, and chooses what to install:

SituationWhat is installed
A new Kitten release for the API version your app declaresKitten, and the new head of the tracked branch when there is one, together
Kitten has a release for a newer API version, and the app still declares the current oneKitten stays on the current API version; the Kitten Settings page shows a notice
The head of the tracked branch declares a newer API version, and a Kitten release for it existsThat release and the new head, together, in one restart
The head declares a newer API version, and no Kitten release for it exists yetNothing for the app; Kitten within the current API version
The head declares an older API version than the running KittenNothing for the app; Kitten within the current API version
The app has no engines.kitten fieldKitten within the current API version; on a requested check, the head as well

An update that fails to start is not tried again; anything newer is. After a Kitten-and-app pair fails, Kitten tries Kitten alone and then the app alone, where the app’s API version allows it. Try again on the Kitten Settings page clears the record of failed updates and checks again.

Before Kitten switches to a new version, it copies the app’s databases. The new version then has a limited time to start and respond to a request for its home page. If it does not, after two attempts, Kitten points back to the previous version and the previous app commit, restores the databases from the copy, and sets aside the databases the new version wrote in updates/failed-data/ under Kitten’s data folder. Nothing in that folder is ever deleted by Kitten. The Kitten Settings page lists the ten newest updates and rollbacks, with the Kitten version of each update linked to Kitten’s change log as it was at that release.

Uploads are not copied or restored.

A rollback restores the databases as they were before the update and sets aside anything written between the switch and the rollback. If your app changes the shape of its data, write migration code that gives existing data the shape the new version needs.

Kitten packages are signed. Kitten installs an update only when its signature verifies against one of the public keys built into Kitten. The one-line installer does not verify the package it downloads.

Kitten’s API version 0 releases (23 April, 9 October, and 21 October 2026) do not automatically update themselves to API version 1. On the 23 April and 9 October releases, the kitten update command moves Kitten to the 21 October release. On the 21 October release, the kitten update command reports that Kitten is up to date. To upgrade to API 1, please run the installer again:

curl -sL https://kittens.small-web.org/install | bash

On a development machine the installer replaces Kitten.

On a production server it installs the new version beside the old one and hands over to the new kitten update command, which upgrades Kitten, and your app alongside it if the app on the tracked branch declares the engines.kitten field in its package.json file. It will also automatically roll back if your upgraded app fails to start with the upgraded Kitten.

If your app does not contain an engines.kitten declaration in its package.json, it will not be upgraded to API version 1. In that case, the kitten update command will exit with error code 1 if the tracked branch has a newer commit, and with success code 0 otherwise.

To prepare an app for API version 1:

  1. Run kitten check in its folder and make the changes it reports

  2. Set the engines.kitten field to "1" in its package.json

  3. Push that commit to the release branch (or to the default branch if there is no release branch)

  4. Run the command, above, to install the latest Kitten on your production server.

If a new version of Kitten cannot start and cannot roll back (e.g., its launcher or update-guard.js has a defect), the service will stop after five restart attempts.

To recover manually, should that happen, in Kitten’s data folder (~/.local/share/small-tech.org/kitten), point app and runtime at the previous version, delete updates/pending, and restart:

cd ~/.local/share/small-tech.org/kitten
ls versions runtimes
ln -sfn versions/<previous version> app
ln -sfn runtimes/<its Node.js version> runtime
rm updates/pending
systemctl --user restart kitten

The Node.js version is the third part of the version’s name.

If the app has also changed, updates/pending will contain a previousAppCommit property. In that case, check out that commit from the app’s folder with git checkout --force --detach <that commit> before you delete the record.

Databases backed up by a rollback can be found in updates/failed-data/.

Production servers require systemd.

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.