How to setup a NethServer Developer Environment

While NethServer is CentOS based, developing new features or simply fixing bugs requires that the developer knows the peculiarities of the templates-events-action system.

- Setup a development machine
- Modify an existing rpm package
- Create a new rpm package
- Create a server-manager UI panel

• NethServer (NS) system used as development machine (can be also a virtual machine)
• GitHub account
• A workstation to edit the files and upload to Github and NethServer machine

On the workstation you will be required to have:

• A text editor to edit files. It is preferable to use one that has syntax checking, like Geany (Linux / Windows).
• A SFTP client like FileZilla (Windows / Linux / OS X ) or WinSCP (Windows) to transfer files from NS to your workstation.
  
• A SSH client (use PUTTY if you are on windows) or in Linux and BSD you can use SSH.

Example of ssh command to connect to NS machine:

ssh filippo@192.168.1.1 -p 2222

*TIP:* In linux you can mount the root of the NS machine as a folder in your File System for easy access.

Note: We will not cover installation of NethServer, to use a Virtual Machine see this link on how to install NS in a VirtualBox

On a clean NethServer system, login as root and install the developer package.
To do this first connect via SSH to your virtual system.

Note: You will need to connect to your NethServer machine on the specified SSH port!
If you changed this in the initial configuration step, you must specify it in the ssh command with the “ -p port” parameter.

ssh root@YourVirtualNethServer -p SSH_port

After you have logged in type:

yum install nethserver-mock

(insert screen with the SSH → yum command)

This command will install into the NethServer the mock package that allows to re-compile the modified files into a package.

After the package installs successfully, we need to create a user that will be used for development.
The user will be added from the NethServer web UI. (we will use filippo as username in this document).

Add the user filippo and set a password for that user.

(insert screen with the web UI → Users)

After the user has been created in the web UI, we need to go to NS shell again to assign the user filippo to the mock group.
This will allow the user to edit files / create packages.

(insert screen with shell)

To add the user to the mock group use this command:

usermod -a -G mock filippo

Logout from the system and login as the created user filippo. Verify that the setup is correct:

$ id
uid=5000(filippo) gid=5000(filippo) groups=5000(filippo),10(wheel),498(mock),508(locals)

* Fork the package on GitHub (we’ll use nethserver-base) * Clone the git repository on the development machine

git clone git@github.com:filippo/nethserver-base.git

• Modify files

Do the needed changes for your modification

• Commit the changes

git commit -a -m “where: what. Refs #”

Example commit message respecting the where-what-refs rule: actions/interface-config-write: create route-ethX files. Refs #1886 A good what should try to complete the following sentence: If applied, this commit will what

• Build the package:

 make-rpms nethserver-base.spec 

As the documentation states make-rpms is sensible to your environment for 'dist' and 'mockcfg'

For ns6

dist=ns6 mockcfg=nethserver-6-x86_64 make-rpms *.spec

For ns7

dist=ns7 mockcfg=nethserver-7-x86_64 make-rpms *.spec

• Export the RPM on a remote virtual system

 scp nethserver-base-<version+release+arch>.rpm root@YourVirtualNethServer:/root 

• Test the RPM on a virtual system

Connect to your NS machine and type:

 yum localinstall nethserver-base-<version+release+arch>.rpm 

• Push modifications to GitHub

 git push 

• Create Pull requests on GitHub

Pull requests let you tell others about the changes you've pushed to a repository on GitHub.
Once a pull request is sent, the interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

• Create a new empty project on GitHub (do not create a readme file)

I prefer to start from an existing package, we’ll use nethserver-postgresql in this example

git clone git@github.com:NethServer/nethserver-postgresql

• Rename the skeleton package to the final package name, we’ll create nethserver-unbound in this example:

mv nethserver-postgresql nethserver-unbound
cd nethserver-unbound
rm -rf .git
git init

• Rename and modify the spec file

mv nethserver-postgresql.spec nethserver-unbound.spec

Diff to show the modifications to specfile (name, version, requirements, description and changelog):

--- nethserver-postgresql/nethserver-postgresql.spec	2015-10-28 15:00:45.445479903 +0100
+++ nethserver-unbound/nethserver-unbound.spec	2015-10-28 15:00:26.015420521 +0100
@@ -1,20 +1,20 @@
-Summary: NethServer postgresql configuration
-Name: nethserver-postgresql
-Version: 1.0.1
+Summary: NethServer unbound configuration
+Name: nethserver-unbound
+Version: 0.1.0
 Release: 1%{?dist}
 License: GPL
 URL: %{url_prefix}/%{name} 
 Source0: %{name}-%{version}.tar.gz
 BuildArch: noarch
 
-Requires: postgresql-server
+Requires: unbound
 Requires: nethserver-base
 
 BuildRequires: perl
 BuildRequires: nethserver-devtools 
 
 %description
-NethServer postgresql configuration
+NethServer unbound configuration
 
 %prep
 %setup
@@ -36,6 +36,3 @@
 %defattr(-,root,root)
 
 %changelog
-* Tue May 19 2015 Giacomo Sanchietti <giacomo.sanchietti@nethesis.it> - 1.0.1-1
-- PostgreSQL database server - Feature #3131 [NethServer]

• Modify createlinks

--- nethserver-postgresql/createlinks	2015-10-28 15:00:45.445479903 +0100
+++ nethserver-unbound/createlinks	2015-10-28 16:06:26.513130255 +0100
@@ -27,12 +27,12 @@
 # actions for nethserver-postgresql-update event
 #--------------------------------------------------
 
-my $event = "nethserver-postgresql-update";
+my $event = "nethserver-unbound-update";
 
 event_actions($event, 
     'initialize-default-databases' => '00',
-    'nethserver-postgresql-conf' => '02' #must be executed before template expansion
+    'nethserver-unbound-conf' => '02' #must be executed before template expansion
 );
-event_templates($event, '/var/lib/pgsql/data/pg_hba.conf');
-event_services($event, 'postgresql' => 'restart');
+event_templates($event, '/etc/unbound/unbound.conf');
+event_services($event, 'unbound' => 'restart');

• Create necessary files, for example templates and configuration database defaults and add them to git:

git add -A

#	new file:   COPYING
#	new file:   createlinks
#	new file:   nethserver-unbound.spec
#	new file:   root/etc/e-smith/db/configuration/defaults/unbound/TCPPort
#	new file:   root/etc/e-smith/db/configuration/defaults/unbound/UDPPort
#	new file:   root/etc/e-smith/db/configuration/defaults/unbound/access
#	new file:   root/etc/e-smith/db/configuration/defaults/unbound/status
#	new file:   root/etc/e-smith/db/configuration/defaults/unbound/type
#	new file:   root/etc/e-smith/templates/etc/unbound/unbound.conf/40unbound_conf

• Commit (no need to respect the where-what-refs rule here)

git commit -a -m “Initial release”

• Build and test as above
• Push to the GitHub repository created in the first step:

git remote set-url origin git@github.com:filippo/nethserver-unbound.git
git push origin master

NethServer project on GitHub: https://github.com/nethserver

(Reference: NethServer developer manual - http://docs.nethserver.org/projects/nethserver-devel/en/latest/building_rpms.html)

How to create a NethServer instance in a VirtualBox Here