Kitten Download Site

kittens.small-web.org serves the latest versions of Kitten distributions, grouped by API version.

A Kitten distribution package name contains version metadata in the following format:

kitten-<API version>-<Git hash>-<Node version>-<Version Stamp>

For example:

kitten-1-6e81f7-20.7.0-20230923100903.tar.xz

Two of the version markers are especially important as far as deployment is concerned:

1. The API version.
2. The Version Stamp.

Kitten apps are written to a specific Kitten API and the Kitten API is versioned using monotonically increasing consecutive numbers, starting at 1.

Each Kitten distribution also has a unique version stamp that is a 14 digit number (date+time stamp of the build) in the form:

YYYYMMDDHHMMSS

A simple integer comparison of two version stamps is enough to know which is the later version (the higher number is the latest version).

Uploads

To upload a new Kitten distribution, send a POST request with multipart/form-data content where the secret token (which you can get from the /settings route on kittens.small-web.org after authenticating with your Kittenmoji secret) is specified in the token field, the content of the distribution package is specified in the package field, and the installer script is specified in the installer field to:

/upload/

For example, using Curl:

curl                                                             \ 
  --verbose                                                      \
  --fail-with-body                                               \
  --form token='<secret token>'                                  \
  --form package='@kitten-1-6e81f7-20.7.0-20230923100903.tar.xz' \
  --form installer='@install'                                    \
  https://kittens.small-web.org/upload

If the version stamp is higher than the latest one for a given API version, the current package for that API version, if any, will be replaced with the uploaded version and served in the future from the download URL for that API version. e.g., for the example above, that would be:

https://kittens.small-web.org/download/1/

The latest package for the latest API version will be served from the /download route. In the example above, if the latest API version is 1, the following route will serve the same package as the more explicit route, above:

https://kittens.small-web.org/download/

The Kittens web site only keeps the latest package for each API version. This should mean that we should be fine in terms of disk space for a long time even on a small VPS plan. If, in the future, this becomes an issue, we can simply upgrade the VPS server’s storage and/or prune very old versions.

Uploads require authentication.

Version check

You can find out the latest version of Kitten by sending a GET request to:

/latest/[API version]/

If the optional [API version] parameter is provided, the response will include a compatible property that lists that latest package available for the given API version, alongside a latest property that has version information for the latest package available for the latest API version (these two might be the same package if the provided API version is the latest API version).

The full JSON response object has the following form:

{
  latest: {
    apiVersion: <number>,
    gitHash: <string>,
    nodeVersion: <string>,
    versionStamp: <number>,
    exactVersion: <string>
  },
  compatible: {
    apiVersion: <number>,
    gitHash: <string>,
    nodeVersion: <string>,
    versionStamp: <number>,
    exactVersion: <string>
  }
}

If the optional argument is not provided, the compatible property will be undefined.

e.g., A possible response to a GET request to https://kittens.small-web.org/latest/1 might be:

{
  "latest": {
    "apiVersion": 2,
    "gitHash": "f25a2b",
    "nodeVersion": "21.5.0",
    "versionStamp": 20231001092312,
    "exactVersion": "2-f25a2b-21.5.0-20231001092312"
  },
  "compatible": {
    "apiVersion": 1,
    "gitHash": "6e81f7",
    "nodeVersion": "20.7.0",
    "versionStamp": 20230923101132,
    "exactVersion": "1-6e81f7-20.7.0-20230923101132"
  }
}

This shows that the latest compatible version (since we asked for API version 1) is 1-6e81f7-20.7.0-20230923101132 and that there is a newer package available with an incompatible (newer) API version of 2.

Based on this information, we can query the app’s repository to see if there is a new version that supports the latest Kitten API version and, if there is, we can transactionally update both the app and Kitten before restarting the server.

If a newer version of the app is not available that supports the latest Kitten API version but there is a newer version of Kitten available for the app’s current API version, we download and install that version of Kitten for the time being until the app is updated to support the latest Kitten API version.

Downloads

To download a Kitten distribution, send a GET request to:

/download/[API version]/

This will download either the latest distribution package or, if specified, the latest distribution package for the specified API version.

Kitten installer

The Kittens site also serves the Kitten installer script (install) at the following route:

/install/[API version]

If the optional [API version] parameter is not provided, the latest installer is served.

Authentication

While downloads are publicly available, uploads require an authentication token to be included along with the upload request.

You can get your authentication token from the private settings page at:

https://kittens.small-web.org/settings

You can also change the token from this page (should the current one be comprimised, for example).

Note that this page requires authorisation to access. You can access it using the project-specific secret for kittens.small-web.org.

License

AGPL version 3.0

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.