The bare minimum

Cockpit’s API makes it easy to create your own pages (or“extensions” if you will) that appear in Cockpit’s menu and interact with your system in any way you like. Our petexample is thePinger which is just the bareminimum: aHTML file with a form toenter an IP, a smallpiece of JavaScriptto call theping Linux command through Cockpitspawn()and capture its output; and amanifest file which tellscockpit how to add it to the menu and where the entry point is.

There is a rather oldblog postwhich explains the Pinger example in detail. Cockpit changed its visual design quite dramatically since then, Pinger’sJavaScript got split into a separate file and does not use jQuery any more, but aside from these details that post isstill generally applicable.

Requirements for real projects

Pinger is great for explaining and understanding the gist of how Cockpit works. But an actual production-ready projectrequires a lot more:

• Separation of HTML, CSS, and JavaScript code: This ensures that your code can use a safeContent-Security-Policy and does not have to use e. g.unsafe-inline. Westrongly recommend this for third-party pages, and absolutely require this for Cockpit’s ownpages.

• Modern frameworks for creating page contents. For any non-trivial page you really don’t want to dabble with piecingtogethermyelement.innerHTML = … strings, but use something likeReact to build pagecontents andPatternFly so that your page fits into Cockpit’s design.

• UseBabel to write your code in modernES6 JavaScript.

• UseESLint to spot functional and legibility errors in your code.

• A build system likewebpack to drive all of the above and build blobs (“minifiedJavascript in a single file”) that are efficiently consumable by browsers.

• Building of release tarballs, source and binary RPMs for testing and distribution.

• Tests to make sure your code keeps working, new features work on all supported operating systems, and changes (pullrequests) get validated.

• As a bonus, easy and safe testing of your page in aVagrant virtual machine.

Sounds complex? It indeed is for someone who is not familiar with the ever-changing “modern” JavaScript world, anddoesn’t want to learn the details of all of these before you can even begin working on your code. This is where theStarter Kit comes in!

Bootstrapping your way from zero to “works!”

TheCockpit Starter Kit is an example project which provides all ofthe above requirements. It provides a simpleReact pagethat uses thecockpit.file() API to read/etc/hostnameand show it. There is also an accompanyingtest that verifies this page. Theother files are mostly build system boilerplate, i. e. the things you don’t want to worry about as the first thing whenyou start a project.

So, how to get this? Make sure you have thenpm package installed. Then check out the repository and build it:

git clone https://github.com/cockpit-project/starter-kit.gitcd starter-kitmake

After that, install (or rather, symlink) the webpack-generated output page indist/ to where cockpit can see it:

mkdir -p ~/.local/share/cockpitln -s `pwd`/dist ~/.local/share/cockpit/starter-kit

Now you should be able to log intohttps://localhost:9090 and see the “Starter Kit” menu entry:

The symlink into your source code checkout is a very convenient and efficient way of development as you can just typemake after changing code and directly see the effect in Cockpit after a page reload.

You should now play around with this a little by hacking src/starter-kit.jsx, runningmake, and reloading the page.For example, try to read and show another file, run a program and show its output, or usecockpit.file(“/etc/hostname”).watch(callback)to react to changes of /etc/hostname and immediately update the page.

Testing

Untested code is broken code. If not here and now, then in the future or some other operating system. This is whyCockpit has a rather complex machinery of regularly building 26 (!) VM images ranging from RHEL-7 and Fedora 27 overvarious releases of Debian and Ubuntu to OpenShift and Windows 8, and running hundreds of integration tests on each ofthem for every PR in an OpenShift cluster.

Replicating this for other projects isn’t easy, and this has been one, if notthe major reason why there aren’t manythird-party Cockpit projects yet. So we now made it possible for third-party GitHub projects to use Cockpit’s CIenvironment, test VM images, and (independently) Cockpit’s browser test abstraction API.

starter-kit uses all three of those: When you runmake check, it will:

• build an RPM out of your current code
• check out cockpit’sbots/ directory that has thecurrent image symlinks and tools to download, customize and run VM images
• check out cockpit’stests/common directory froma stable Cockpit release (as the API is not guaranteed to be stable)which provides a convenient Python API for theChrome DevTools protocol
• download Cockpit’s current CentOS-7 VM image; you can test on a different operating system by setting the environmentvariableTEST_OS=fedora-27 (or a different operating system - but note that starter-kit does not currently builddebs)
• create an overlay on that pristine centos-7 image with the operating system’s standard “cockpit” package and yourlocally built starter-kit RPM installed
• run a VM with that overlay image with libvirt and QEMU
• launch a chromium (or chromium-headless) browser
• Run the actualcheck-starter-kittest which instructs the web browser what to do and which assertions to make

[starter-kit] $ make check[...]rpmbuild -bb [...] cockpit-starter-kit.spec[...]git fetch --depth=1 https://github.com/cockpit-project/cockpit.gitFrom https://github.com/cockpit-project/cockpit * branch            HEAD       -> FETCH_HEADgit checkout --force FETCH_HEAD -- bots/[...]bots/image-customize -v -r 'rpm -e cockpit-starter-kit || true' -i cockpit -i `pwd`/cockpit-starter-kit-*.noarch.rpm -s /home/martin/upstream/starter-kit/test/vm.install centos-7[...]TEST_AUDIT_NO_SELINUX=1 test/check-starter-kit1..1# ----------------------------------------------------------------------# testBasic (__main__.TestStarterKit)#ok 1 testBasic (__main__.TestStarterKit) # duration: 21s# TESTS PASSED [22s on donald]

Note that the first time you run this will take a long time due to the rather large VM image download. But it will bereused for further tests.

For writing your own tests with the Cockpit Python API, have a look at theBrowser andMachineCase classes intestlib.py. These provide bothlow-level (likeclick() orkey_press()) and high-level (likelogin_and_go()) methods for writing test cases. Andof course you have a wealth ofCockpit tests forgetting inspiration.

starter-kit itself is also covered by Cockpit’s CI, i. e. pull requests will run tests on CentOS 7 and Fedora 27(example, click on “View Details”). Please come and talk to usonce your project is mature enough to do the same, then we can enable automatic pull request testing on your project as well.

Using different technologies

starter-kit makes opinionated choices like using React, webpack, and Cockpit’s testing framework. These are thetechnologies that we use for developing Cockpit itself, so if you use them you have the best chance that the Cockpitteam can help you with problems. Of course you are free to replace any of these, especially if you have already existingcode/tests or a build system.

For example, it is straightforward to just use Cockpit’s test images with theimage-customize tool and running theseas ephemeral VMs withtestvm.py, butnot use Cockpit’stest/common. Tests can also be written with e. g.puppeteerornightmare. I will write about that separately.

Feedback

starter-kit is still fairly new, so there are for sure things that could work more robustly, easier, more flexibly, orjust have better documentation. If you run into trouble, please don’t hesitate telling us about it, preferably byfiling an issue.

Happy hacking!

The Cockpit Development Team