Skip to content


This document describes how to create a new application from scratch.

A NethServer Cockpit module is composed by 5 parts:

  • UI: a mix of HTML and CSS which presents data loaded using JavaScript (Cockpit API or NethServer API)
  • API: a list of helpers to do actions: read - validate - update
  • Package files: manifest and RPM spec file to create an installable package
  • Translation files (optional)
  • An application manifest

Install required tools

Let's assume you've already prepared your own development environment.

git clone your-own-module

cd your-own-module
├── api
   ├── read
   ├── update
   └── validate
├── createlinks
├── nethserver-cockpit-empty.json
├── nethserver-cockpit-empty.spec
├── prep-sources
└── ui
    ├── css
       └── style.css
    ├── dev
       ├── cockpit.min.js
       ├── jquery.min.js
       └── patternfly.css
    ├── i18n
       └── language.json
    ├── index.html
    ├── js
       ├── app.js
       └── lib
           ├── sammy.js
           └── sammy.template.js
    ├── logo.png
    ├── manifest.json
    ├── override.json
    └── views
        ├── about.html
        ├── dashboard.html
        ├── item1.html
        └── logs.html

8 directories, 26 files


NethServer provides a set of tool for building RPMs under CentOS or Fedora. Prepare the build environment, then create the RPM for your module:

Change occurencies

Sobsitute all nethserver-cockpit-empty and NethServer Cockpit Empty occurencies with your-own-module and Your Own Module, to check all occurencies:

grep -Rn 'nethserver-cockpit-empty' *
grep -Rn 'NethServer Cockpit Empty' *

Rename also nethserver-cockpit-empty-json and nethserver-cockpit-empty-spec with your-own-module.json and your-own-module.spec.

Build the module:

make-rpms your-own-module.spec

Then you have rpm builded inside the directory, install it, inside NethServer machine with

scp your-own-module-x.y.z-t.ns7.noarch.rpm root@

ssh root@

yum install your-own-module-x.y.z-t.ns7.noarch.rpm

You can see the module in action by accessing Cockpit: https://<your_server>:9090, in the Applications section.

If some JavaScript or HTML part doesn't load correctly, execute:

systemctl restart cockpit


Edit all application metadata inside the manifest:


It's now time to start implementing some nice feature, you just need to know HTML, CSS and some JavaScript basics: there is no need to learn a new framework, use whatever you like.

The source code must be placed inside the app directory:

  • index.html: main HTML template, contains the navbar left menu with 3 base sections:
  • Dashboard
  • Item 1 (can be customizable)
  • Logs
  • About
  • css/style.css: application stylesheet, customize your custom CSS but always follow UI guidelines
  • js/app.js: JavaScript logic goes here. If you need to develop complex API, take a loot to API guidelines
  • views/*.html: contains views for each routes defined in app.js

You can ignore manifest.json and override.json files which are used for Cockpit internals (change only name inside with your-own-module).

  • The module UI will be installed inside /usr/share/cockpit/<project> directory.
  • The module API will be installed inside /usr/libexec/nethserver/api/<project> directory.
  • Metadata will be copied inside /usr/share/nethserver/applications directory.

A new application card named as your project will be added to the Applications page.

JavaScript frameworks

The module provides a very small and easy routing system and javascipt API but in case you really want to pick a JavaScript framework, just include it inside index.html.

AngularJS (

<html ng-app>
<script src=""></script>

Vue (

<script src=""></script>

React (

<script crossorigin src=""></script>
<script crossorigin src=""></script>

Save your work

The code should always be kept under a version control system for tracking changes. NethServer build system assumes you're using git, so commit everything on a git repository:

git init
git add *
git commit -a -m "First import"

Always consider to share your code, take a look at GitHub.