**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 <https://metacpan.org/pod/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 <https://rollupjs.org/>`_: ``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 <https://rollupjs.org/>`_.

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`