Technical Manual sections
Reference › Technical Manual › Data
Kitten stores its own files and the data of every app it serves under one data home, ~/.local/share/small-tech.org/kitten/ (paths.KITTEN_DATA_HOME). Kitten follows the XDG Base Directory Specification, so setting XDG_DATA_HOME to an absolute path moves it. src/lib/paths.ts defines Kitten’s paths. The global kitten.paths object exposes them (except the ones in updatePaths) along with the paths of the app being served (APP_DATA_DIRECTORY, APP_UPLOADS_DIRECTORY, and APP_REPL_DIRECTORY).
The data home contains:
app/: a symbolic link to the installed distribution inversions/. (app/web/is Kitten’s internal web app.)versions/<exact version>/: one folder per installed Kitten version (the active one and the previous one). Step 3 of How it works describes the folder’s name.runtime/: a symbolic link to the Node.js runtime of the installed distribution inruntimes/.runtimes/<version>/: the installed Node.js runtimes.tls/local/andtls/global/: localhost and Let’s Encrypt certificates.data/:__db/: the global internal database (kitten.__db).<project identifier>/: one folder per app (kitten.paths.APP_DATA_DIRECTORY), which contains:db/: the app database (kitten.db),_db/: Kitten’s internal database for the app (kitten._db),uploads/: uploaded files, andrepl/: the interactive shell’s history.
updates/: the state of automatic updates (see Updates).deployments/: working copies of apps deployed withkitten deploy.clones/: working copies of apps run withkitten run.tmp/: temporary files on the same file system as the data.
Outside the data home, Kitten writes:
the
kitten,kitten-node, andkitten-npmcommands in ~/.local/bin/ (symbolic links to app/kitten and to the runtime’s bin/node and bin/npm), andthe systemd unit of a deployed app (~/.config/systemd/user/kitten.service).
The data/ folder also marks the data layout as current: if it doesn’t exist when Kitten starts, the main script runs the data encapsulation migration.
Kitten uses JSDB for all three of its databases. Each top-level property of a database is a table, which JSDB persists as a JavaScript file that starts with the table’s initial value, followed by one line per change. When Kitten opens kitten.db or kitten._db, JSDB compacts their tables, unless the jsdbCompactOnLoad environment variable is 'false' (the kitten db commands set it). JSDB never compacts kitten.__db.
kitten.db(src/AppDatabase.ts) is the app’s own database, indb/. If the app has a database app module (app_modules/database/database.ts or database.js, with the TypeScript file taking precedence), Kitten imports it, calls itsinitialise()function with{ internalClasses: { Upload } }, and uses the database it returns. If there is no database app module, or itsinitialise()function returnsundefined, Kitten opensdb/itself with theUploadclass registered.kitten._db(src/InternalDatabase.ts) is Kitten’s internal database for the app, in_db/. Its tables are:settings: the owner’s public keys (id) and the place’s settings (seeKittenInternalDatabasein src/types/globals.d.ts),sessions: signed-in sessions only (see Sessions and sign-in),uploads: anUploadscollection, which is alsokitten.uploads,stats: request statistics (see the stats middleware in Middleware), andscheduledRestart: the hour of the daily restart in production and the date of the last one.
kitten.__db(src/GlobalInternalDatabase.ts) is the global internal database, indata/__db/, which every app on the machine shares. Its only table,state, records whether a Catalyst instance is deploying this server (isBeingDeployedByDomain). Kitten opens it in main.ts, before the command-line interface runs, so that commands likekitten deploycan use it.
Remember that JSDB doesn’t persist properties whose names start with an underscore, and that it calls the constructor of each registered class with one parameter object when it loads a table. A class that you add to INTERNAL_DATABASE_CLASSES must accept that object.
Source code: