Reference sections
Reference âș Deployment
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.
If you are making a Small Web app for everyday people, declare the Kitten API version it supports in its package.json (see Versioning). Kitten then checks for updates to your app and to itself, installs them together, and rolls back an update that does not start.
If you are building something for yourself and are happy to update the site by hand, you can do so from the App Settings page of your Kitten site (/đ±/settings/app/).
If you want your Kitten site to update every time you push to its tracked branch, set up a webhook.
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:
- From your projectâs repository, follow the Settings link.
- In the Settings menu, select Webhooks.
- Press the Add webhook button.
- From the buttonâs pop-up menu, select Forgejo.
- Enter the Webhook URL from below into the Target URL field.
- Leave the HTTP method set to
POST. - Set the POST content type to
application/x-www-form-urlencoded. - Leave the Secret field empty.
- Set Trigger on to
Push events - Set Branch filter to the branch Kitten tracks:
releaseif your repository has one, your default branch otherwise (the App Settings page shows which) - Enter the Webhook secret from below into the Authorization header field.
- Leave the Active checkbox checked.
- 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:
The
releasebranch if the repository has oneThe default branch otherwise (likely
main).
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:
- Push to its tracked branch after setting up a webhook in its Kitten Settings
- Use the Update to latest commit button on the App Settings page
- Use the Check now button on the Kitten Settings page
- Run
kitten updateon the server.
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:
| Situation | What is installed |
|---|---|
| A new Kitten release for the API version your app declares | Kitten, 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 one | Kitten 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 exists | That release and the new head, together, in one restart |
| The head declares a newer API version, and no Kitten release for it exists yet | Nothing for the app; Kitten within the current API version |
| The head declares an older API version than the running Kitten | Nothing for the app; Kitten within the current API version |
The app has no engines.kitten field | Kitten 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:
Run
kitten checkin its folder and make the changes it reportsSet the
engines.kittenfield to"1"in its package.jsonPush that commit to the
releasebranch (or to the default branch if there is noreleasebranch)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.