Kitten

Technical Manual sections

These are the rules that shape and drive Kitten’s development.

What separates a Small Web site from a Big Web site is who owns and controls it.

Kitten is a tool for building Small Web sites and apps, which are owned and controlled by individuals. Our greatest advantage is simplicity. Specifically, it’s the complexity we avoid by limiting Small Web servers to a single app with a single owner.

This fundamental design decision removes a whole class of complexity: we don’t have “users” or “accounts”, we have “the owner”. We don’t have to worry about roles, etc., during authentication and authorisation, etc.

A Kitten server, therefore, serves one app for the one person who owns it.

During development and on your local machine, you can run as many servers as you like. The test suites, for example, run several instances of one app at the same time, each at its own port, using the Kitten helper in tests/helpers/Kitten.ts.

Similarly, when testing peer-to-peer Small Web apps, you can run multiple instances locally using the place1.localhost, place2.localhost, etc., aliases.

We follow web standards and good practices (semantic HTML, accessible code, etc.)

We don’t implement what the browser or the operating system already provides. (For example, Kitten has no idle timeout, because an unattended device is the screen lock’s job.)

We value simplicity and we’re always on the look out for how we can make Kitten simpler, more elegant, and easier to use.

While you can build traditional, centralised web apps with Kitten (or just have it serve your static web site from 1993), Kitten is designed for the Small Web. That is to say, the personal, peer-to-peer web.

When designing Kitten features and Kitten apps, we keep the following principles in mind:

This is why Auto Encrypt Localhost exists, for example (so we can use TLS in development).

Development and production differ only where they must. Kitten runs in production when the PRODUCTION environment variable is true, as it is in the systemd unit written by the kitten deploy command.

In production, Kitten:

In development, a change to any file in the project (except those in node_modules/ and in hidden files and folders other than .well-known/) exits the worker with the restart request code (systemExitCodes.restartRequest, which is 99), and the Kitten Process Manager forks a new worker (see File changes). An uncaught exception exits with the same code.

In production, systemd restarts Kitten after any non-clean exit (see Errors and restarts).

Slow tests are tests people don’t run. We measure and track wall clock time of tests to ensure that we run them often.

When Kitten catches an error on an author’s behalf, it must print a message that explains the issue to the author in plain language and provides information they can act on. If there are known/possible fixes, mention them.

All Kitten data is stored under kitten.paths.KITTEN_DATA_HOME, and each app’s data is in its own subfolder of kitten.paths.KITTEN_DATA_DIRECTORY (kitten.paths.APP_DATA_DIRECTORY), the name of which is the app’s project identifier (see Serve and, for random ports, Domains and domain aliases). We never store Kitten or app data outside of those folders.

We keep the reference, tutorials, and this technical manual up to date as we continue to develop Kitten.

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.