Scaffolding for a Cockpit module.
On Debian/Ubuntu:
$ sudo apt install gettext nodejs npm make
On Fedora:
$ sudo dnf install gettext nodejs npm make
These commands check out the source and build it into the dist/ directory:
git clone https://github.com/cockpit-community/cockpit-mail.git
cd mail
make
make install compiles and installs the package in /usr/local/share/cockpit/. The
convenience targets srpm and rpm build the source and binary rpms,
respectively. Both of these make use of the dist target, which is used
to generate the distribution tarball. In production mode, source files are
automatically minified and compressed. Set NODE_ENV=production if you want to
duplicate this behavior.
For development, you usually want to run your module straight out of the git
tree. To do that, run make devel-install, which links your checkout to the
location were cockpit-bridge looks for packages. If you prefer to do
this manually:
mkdir -p ~/.local/share/cockpit
ln -s `pwd`/dist ~/.local/share/cockpit/mail
After changing the code and running make again, reload the Cockpit page in
your browser.
You can also use watch mode to automatically update the bundle on every code change with
$ ./build.js -w
or
$ make watch
When developing against a virtual machine, watch mode can also automatically upload
the code changes by setting the RSYNC environment variable to
the remote hostname.
$ RSYNC=c make watch
When developing against a remote host as a normal user, RSYNC_DEVEL can be
set to upload code changes to ~/.local/share/cockpit/ instead of
/usr/local.
$ RSYNC_DEVEL=example.com make watch
To "uninstall" the locally installed version, run make devel-uninstall, or
remove manually the symlink:
rm ~/.local/share/cockpit/mail
Cockpit Starter Kit uses ESLint to automatically check
JavaScript code style in .js and .jsx files.
eslint is executed within every build.
For developer convenience, the ESLint can be started explicitly by:
$ npm run eslint
Violations of some rules can be fixed automatically by:
$ npm run eslint:fix
Rules configuration can be found in the .eslintrc.json file.
Cockpit uses Stylelint to automatically check CSS code
style in .css and scss files.
styleint is executed within every build.
For developer convenience, the Stylelint can be started explicitly by:
$ npm run stylelint
Violations of some rules can be fixed automatically by:
$ npm run stylelint:fix
Rules configuration can be found in the .stylelintrc.json file.
During fast iterative development, you can also choose to not run eslint/stylelint. This speeds up the build and avoids build failures due to e. g. ill-formatted css or other issues:
$ ./build.js -es
Run make check to build an RPM, install it into a standard Cockpit test VM
(centos-8-stream by default), and run the test/check-application integration test on
it. This uses Cockpit's Chrome DevTools Protocol based browser tests, through a
Python API abstraction. Note that this API is not guaranteed to be stable, so
if you run into failures and don't want to adjust tests, consider checking out
Cockpit's test/common from a tag instead of main (see the test/common
target in Makefile).
After the test VM is prepared, you can manually run the test without rebuilding the VM, possibly with extra options for tracing and halting on test failures (for interactive debugging):
TEST_OS=centos-8-stream test/check-application -tvs
It is possible to setup the test environment without running the tests:
TEST_OS=centos-8-stream make prepare-check
You can also run the test against a different Cockpit image, for example:
TEST_OS=fedora-34 make check
These tests can be run in Cirrus CI, on their free
Linux Containers environment which
explicitly supports /dev/kvm. Please see Quick
Start how to set up Cirrus CI for
your project after forking from mail.
The included .cirrus.yml runs the integration tests for two operating systems (Fedora and CentOS 8). Note that if/once your project grows bigger, or gets frequent changes, you may need to move to a paid account, or different infrastructure with more capacity.
Tests also run in Packit for all currently supported Fedora releases; see the packit.yaml control file. You need to enable Packit-as-a-service in your GitHub project to use this. To run the tests in the exact same way for upstream pull requests and for Fedora package update gating, the tests are wrapped in the FMF metadata format for using with the tmt test management tool. Note that Packit tests can not run their own virtual machine images, thus they only run @nondestructive tests.
After cloning the Starter Kit you should rename the files, package names, and labels to your own project's name. Use these commands to find out what to change:
find -iname '*starter*'
git grep -i starter
Once your cloned project is ready for a release, you should consider automating that. The intention is that the only manual step for releasing a project is to create a signed tag for the version number, which includes a summary of the noteworthy changes:
123
- this new feature
- fix bug #123
Pushing the release tag triggers the release.yml
GitHub action workflow. This creates the
official release tarball and publishes as upstream release to GitHub. The
workflow is disabled by default -- to use it, edit the file as per the comment
at the top, and rename it to just *.yml.
The Fedora and COPR releases are done with Packit, see the packit.yaml control file.
It is important to keep your NPM modules up to date, to keep up with security updates and bug fixes. This is done with the npm-update bot script which is run weekly or upon manual request through the npm-update.yml GitHub action.
- The Starter Kit announcement blog post explains the rationale for this project.
- Cockpit Deployment and Developer documentation
- Make your project easily discoverable