This document will guide you, a developer, on how to create a new rootless module. The module will be a simple NethServer package containing an HTTP echo server.
- How to create a rootless module
This tutorial will use some GitHub features to ease the module setup phase. While you do not really need a GitHub account to develop NS8, you will need it if you want to follow this guide step-by-step.
On your machine you will also need GIT and a text editor.
Name your repo with
ns8-mymodule). Do not end your module name with a number, like
Clone the repository and follow the instructions inside the README
It’s now time to modify the code and implement your module.
Start easy and just edit the
README.md file, by replacing this section with your module
Each module is distributed using a container image.
A module is usually composed by the following main parts:
imagerootdirectory, contains all scripts to configure the module
uidirectory, contains all user interface files
build-images.sh, a script to manually build one or more images of the module and eventually push them inside the image registry
README.mddescribes module implementation and usage
The module is something like an RPM or DEB file: it contains the configuration of the application that will run inside NS8. During the installation process the system will download the real application (eg. Wordpress, Samba) and configure it using the actions from the module.
imageroot directory will be extracted to the system during the module install.
It contains 2 main paths:
actionscontains all actions for the module agent, the directory will be copied to
systemd/user/contains all systemd
.servicefiles, the directory will be copied to
Usually, a module contains also a
configure-module action to gather user input and configure the module accordingly.
configure-module action should:
- validate user input
- set environment variables and eventually expand the configuration
- enable and start the systemd unit(s)
- setup Traefik proxy routes, if needed
Make sure that all parameters used by
configure-module are saved inside the environment.
Such parameters could than be retrieved by a
get-configuration action, used to display the configuration inside the UI.
The script creates an empty container image and publish it to the registry on user request.
The main parts to look for are:
repobase: the URL of the remote image registry
reponame: the name of the module
- labels for basic module setup
No matter on which node the module will run, the web user interface will be automatically imported inside the leader node
and it will be available from the admin URL
See how to setup and develop the UI.
Also make sure to edit
imageroot/ui/public/metadata.json and replace the logo at
Commit your local changes, than push it to GitHub repository.
After the push, GitHub will build the module as a container image and publish it to GitHub registry.
The module will be available under your namespace like
Published image will contain the name of the branch, or tag, as version like
latest version will always point to the latest build from the main branch, like
Another workflow will also build the API documentation from JSON schema and publish the result inside the
mybranch is the current pushed git branch or tag. Default is
You can build your modules locally using any distribution which supports
To build the image, just execute
bash build-images.sh script.
Before pushing images to the registry, you must configure the authentication.
Create a GitHub Personal Access Token (PAT)
for the ghcr.io registry (for read-only access
read:packages private scope should be enough) then run the following command, specifying
your GitHub user name and providing the generated PAT as password:
buildah login ghcr.io
build-images.sh script will output the command to push the images to
the registry. Example:
buildah push ghcr.io/myuser/mymodule docker://ghcr.io/myuser/mymodule:latest
If you didn’t it already, it’s now time to install NS8.
You are going an SSH connection to the cluster leader to follow below steps.
First, we have to tell the cluster leader to instantiate a new module. The node agent will
create a new Unix user that runs the rootless module and schedule the
action to start soon.
Just install the module straight from the image registry, without using NethServer package repository:
add-module ghcr.io/myuser/mymodule:latest 1
In case of error, see
You can now access the module configuration at
https://your.server.fqdn/cluster-admin or navigate directly
to the application at
Repeat steps from 2 to 4 until you’re module is ready for prime time!
This step is optional. Follow below instructions only if you want to make your package publicly available from a software repository accessible inside the administration UI.
If you want to publish the package, first make sure the package as a tag which is a valid semantic version. Then create a new Pull Request (PR) to ns8-repomd repository. The PR should contain:
- a new directory with the name of the module
- the directory should also contain a
screenshotssubdirectory with one ore more screenshots (optional)
If the package is not hosted on GitHub under NethServer organization, you must also add:
When the PR has been merged, repository metadata will be automatically updated accordingly.