Layout of Package Files

A package consists of one or more files placed in a directory or its subdirectories. It must have a manifest.json file and follow certain naming conventions.

The name of a package is the name of the directory.

The name of the package must be ASCII alphanumeric, and may contain an underscore. Names of directories and files in the package must consist of ASCII alphanumeric along with dash, underscore, dot, and comma. No spaces are allowed.

Cockpit uses the data directories from the XDG Base Directory Specification to locate packages. The $XDG_DATA_DIRS represents a colon separate list of system data directories, and $XDG_DATA_HOME is a user specific data directory. If the environment variables are not set, defaults are used, according to the spec.

A cockpit/ subdirectories in any of these data directories is the location where packages are loaded by Cockpit. If Cockpit finds a package with the same name, in multiple data directories, then the first one wins. According to the spec the first data directory is $XDG_DATA_HOME and then $XDG_DATA_DIRS in order.

This means that, by default the following directories are searched for cockpit packages, and in this order:

Packages placed in $XDG_DATA_HOME are not cached by Cockpit or the web browser. Other packages are cached agressively, and are accessed using a checksum of the files in the packages and their names.

To further clarify things, here is an example package called "my-package" and its file layout:

/usr/share/cockpit/
    my-package/
        manifest.json
        file.html
        some.js

Place or symlink packages in your ~/.local/share/cockpit directory (or appropriate $XDG_DATA_HOME location) that you would like to modify and develop. System installed packages should not change while Cockpit is running.