Skip to content

Tutorial

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 git@github.com:NethServer/nethserver-cockpit-empty.git your-own-module

cd your-own-module
.
├── api
│   ├── read
│   ├── update
│   └── validate
├── COPYING
├── createlinks
├── nethserver-cockpit-empty.json
├── nethserver-cockpit-empty.spec
├── prep-sources
├── README.md
└── 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

Build

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:

./prep-sources
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@192.168.1.20:

ssh root@192.168.1.20

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

Customize

Edit all application metadata inside the manifest:

your-own-module.json

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 (https://angularjs.org/):

<html ng-app>
...
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.5.6/angular.min.js"></script>

Vue (https://vuejs.org/):

<script src="https://unpkg.com/vue"></script>

React (https://reactjs.org/):

<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></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.