Cockpit Packages

Layout of Package Files
Package Manifest
Package Links and Paths
Minified Resources
Using Cockpit API

Cockpit is separated into various packages, each of which brings specific features and/or code.

Warning

It is not yet possible to implement arbitrary new packages.

In addition, any APIs or behavior not explicitly documented here is an internal API and can be changed at any time.

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:

  • ~/.local/share/cockpit/

  • /usr/local/share/cockpit/

  • /usr/share/cockpit/

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.

Package Manifest

Each package has a manifest.json file. It is a JSON object. The following fields may be present in the manifest:

alias

Additonal package name or names for this package. If a string, then just one name, if an array then multiple names. These names are usually well-known names that the package should provide resources for.

version

An informational version number for the package.

Package Links and Paths

When referring to files in your package, such as in a hyperlink or a <style> tag or <script> tag, simply use a relative path, and refer to the files in the same directory.

However often the need arises to refer from one package to another, for example when loading the base cockpit.js javascript. To do this the path must be crafted in a specific way: ../@@package@@/path

The @@package@@ is replaced by the relevant path component to address the the package. Put the package name between the @@ signs. It will be replaced with a cacheable checksum of the package, or qualified package name at the given host. Don't hardcode the path, use the @@ syntax.

For example here's how to include the base cockpit.js script in your HTML from the latest package:

  <script src="../@@latest@@"></script>

Do not assume you can link to any file in any other package. Refer to the list of API packages for those that are available for use.

Minified Resources

If minified resources are provided, they should be provided along with the non-minified file. This allows developers to debug package code when necessary.

Minified files should contain a .min suffix before their usual file extension. They will automatically be used in place of the unminified file, when your the package is installed. This applies for HTML, JS, CSS or other types of resources.

For example if you have a javascript file called test.js its minified version should be placed in a file called test.min.js in the same directory.

To force Cockpit to use non-minified resources, link the package into your home directory as described in the section on Package Layout.

Using Cockpit API

Cockpit has API available for writing packages. There is no API available for external callers to invoke via HTTP, REST or otherwise.

Warning

Unless an API is explicitly marked as stable, it is unstable and can be changed when Cockpit is upgraded.

API from various packages can be used to implement Cockpit packages. Each package listed here has some API available for use. Only the API explicitly documented should be used. In some cases even though the API is available it is not (yet) stable.

To include javascript from the API, simply load it into your HTML using a script tag. Alternatively you can use an javascript loader. Always refer to the package using the @@package@@ syntax. This allows Cockpit to optimize and cache multiple uses of the same resources.