Do you want to contribute to LemonLdap::NG project ?

Contribute to Project

LemonLDAP::NG is mostly written in Perl and Javascript. Community applies the following rules:

  • Perl:

    • code must be written in modern object-oriented code (using Mouse) (except handler and Apache::Session inheritance)

    • code must be formatted using the make tidy command

  • Javascript:

    • Javascript code is written in <component>/site/js-src and bundled using rollupjs: make minify will generate JS files

Get code

Configure SSH

On Debian developper station :

ssh-keygen -o -t rsa -b 4096 -C "your@email"

Go to your gitlab account : https://gitlab.ow2.org/profile/keys

cat ~/.ssh/id_rsa.pub

Copy id_rsa.pub content to key section and enter a name into “Title” and click “Add key” button. Test ssh connexion :

ssh -T git@gitlab.ow2.org

Accept messages

Configure Git

As user:

git config --global user.name "Name Surname"
git config --global user.email "your@mail"
git config --global color.ui true
git config --list

Clone repository

As user, create directory in directory:

git clone git@gitlab.ow2.org:lemonldap-ng/lemonldap-ng.git
cd lemonldap-ng/

# Use your own clone for pushes
git remote set-url --push origin git@gitlab.ow2.org:user/lemonldap-ng.git

Run LemonLDAP::NG

Container-based setup

The following commands are based on Podman <https://podman.io/>. To get them working in a Docker environment, just replace podman with docker.

Build image:

podman build . -t llng-local-dev

Start container:

podman run -it -v ./:/app -p 8080:8080 -p 3000:3000 llng-local-dev

Open http://auth.llng.localhost:8080/ in your browser.

Run tests:

podman run -it -v ./:/app llng-local-dev make test

Note

this will not be efficient if you want to run tests multiple times (eg while developing) as the patch and build steps will be run each time. You can speed-up this by starting the dev. server container, then running your tests inside the running container with the following command.

podman exec -it <container-id> make test

Manual setup

Install basic tools

As root:

apt install make devscripts equivs yui-compressor git uglifyjs rollup node-rollup-plugin-babel autopkgtest cpanminus

Install dependencies

# Install build dependancies
mk-build-deps debian/control
sudo apt install ./lemonldap-ng-build-deps*deb
apt install apache2 libapache2-mod-fcgid libapache2-mod-perl2  # install Apache
cpanm Perl::Tidy@$(make tidyversion)

For SAML:

apt install liblasso-perl libglib-perl

Configure hosts file

echo '127.0.0.1       auth.example.com manager.example.com test1.example.com test2.example.com' >> /etc/hosts

Unit tests

Launch unit tests:

make test # or manager_test, portal_test, ... to launch unit tests

Same tests launched on a simulated install

make autopkgtest # or autopkg_portal, autopkg_manager, ... to launch unit tests

Execute an unit test :

# Building project
cd ~/lemonldap-ng/; make
# Go to parent test directory
cd ~/lemonldap-ng/lemonldap-ng-portal
# and execute the unit test:
prove -v t/67-CheckUser.t

# Run unit test at debug log level
DEBUG=1 prove -v t/67-CheckUser.t

Launch tests with LDAP backend

apt install slapd
make LLNGTESTLDAP=1 test

Note

slapd might fail to start if you use Apparmor or SELinux, check your system logs if that happens

Other commands

  • Start a test web server on port 19876:

    make start_web_server # TESTUSESSL=1 to enable SSL engine (only available for Apache)
make start_web_server TESTWEBSERVER=nginx # to use Nginx web server
make stop_web_server
make reload_web_server # to reload LL:NG conf

  • Clean test files

    make clean

  • Compile Javascript and minify

    make minify

  • Rebuild manager tree, this is needed everytime you add a new option

    make json

  • Update Perl manifest

    make manifest

  • Reformat Perl files

    make tidy

Add a translation key

If you need to create a new parameter in Manager or add a new message in Portal, you must add a key in JSON languages files.

To ease this process, use the script scripts/addTrEntry provided in the sources:

$ scripts/addTrEntry
Usage:
scripts/addTrEntry <option> key enText <frText>
scripts/addTrEntry <option> key '$otherkey'

Options:
  --portal  -p: add entry in portal translation instead of manager
  --modify  -m: modify an existing entry
  --delete  -d: delete an existing key
  --reorder -r: reorder files
  --help   -h: display this

For example:

$ scripts/addTrEntry MyNewParameter 'A new parameter' 'Un nouveau paramètre'

Documentation

Install dependencies:

apt install python3-sphinx python3-sphinx-bootstrap-theme

Then edit sources in doc/sources/admin.

You can check the result with:

make documentation
firefox doc/pages/documentation/current/start.html

Javascript

Javascript code is produced by rollupjs.

Source script must be created in lemonldap-ng-portal/site/js-src, then run this command:

make minify

On Debian, you can install rollupjs and the needed dependencies with:

apt install rollup node-rollup-plugin-babel

Debugging

$req and req->{env} variables can be dumped by using logParams = 1 in lemonldap-ng.ini file. High debug level can be enabled in Manager/Conf/Parser.pm with HIGHDEBUG => 1