4. Customization

When talking about customization, we should distinguish between:

  1. Server customization

  2. User accounts customization

  3. Client customization

4.1. Server customization

GIS.lab Server (master node) can be customized by running standard Linux/Ubuntu commands. See GISMentors training group customization for example of customization performed by specific Ansible Playbooks.

But it is recommended to use some isolated environment like LXC or Docker containers when deploying custom service. See Gisquick integration section for example of such customization.

See also

see Understanding the key differences between LXC and Docker

4.2. User accounts customization

Process of creation and removal of GIS.lab user accounts can be customized by special scripts.

Important

imp Scripts must have executable permissions assigned and can’t contain file extension, see man run-parts.

Directory /opt/gislab/custom/accounts in Fig. 4.1 (located on GIS.lab master node) contains following directories with customization scripts.

  • before-add - executed before account is created

  • after-add - executed after account is deleted

  • before-delete - executed before account is deleted

  • after-delete - executed after account is deleted

  • files - content of this directory is copied to user’s home directory before after-add hooks are executed

../_images/customization-files.svg

Fig. 4.1 File layout related to customization.

In above customization scripts it is possible to use various variables. When creating or deleting GIS.lab user account using gislab-adduser and gislab-deluser administration commands, following variables can be used.

  • GISLAB_USER - user name

  • GISLAB_USER_GIVEN_NAME - first name

  • GISLAB_USER_SURNAME - last name

  • GISLAB_USER_EMAIL - email

  • GISLAB_USER_DESCRIPTION - description

  • GISLAB_USER_SUPERUSER - superuser status

  • GISLAB_USER_GROUPS - groups membership

For content stored in files directory, it is possible to use template variables in following format.

  • gislab-adduser

    • {+ GISLAB_USER +} - user name

    • {+ GISLAB_USER_GIVEN_NAME +} - first name

    • {+ GISLAB_USER_SURNAME +} - last name

    • {+ GISLAB_USER_EMAIL +} - email

    • {+ GISLAB_USER_DESCRIPTION +} - description

    • {+ GISLAB_USER_SUPERUSER +} - superuser status

    • {+ GISLAB_USER_GROUPS+} - groups membership

Example customization script db in after-add directory for automatic database schema creation in schemaname after new GIS.lab user is added is shown below.

#!/bin/sh

create_schema() {
    if [ ! -z `sudo -u postgres psql -lqt | cut -d \| -f 1 | grep -w $1` ]; then
        echo "CREATE SCHEMA $GISLAB_USER;
GRANT USAGE on SCHEMA $GISLAB_USER to $GISLAB_USER;
GRANT SELECT ON ALL TABLES IN SCHEMA $GISLAB_USER TO $GISLAB_USER;
GRANT all ON SCHEMA $GISLAB_USER to $GISLAB_USER" | \
            sudo -u postgres psql $1
    fi
}

create_schema schemaname

exit 0

4.3. Client customization

GIS.lab desktop client can be customized by running standard Linux/Ubuntu commands as well as GIS.lab server. Difference is that they must be executed in isolated environment called chroot. Administrator commands gislab-client-shell and gislab-client-image are used to perform this action.

Fundamental is an image file. It is a binary file with the .img filename extension and represents a snapshot GIS.lab client operating system. More specifically, it is compressed client’s root. GIS.lab clients boots from this image. The first of above mentioned commands enables to enter chroot environment. The second command creates a new updated image file.

Danger

danger Client’s root and resulting image are always restored to original state after every GIS.lab upgrade, so customization must be applied again.

Note

note This behaviour is planed to be changed in future.

Important danger note written above is precisely why backup should always be used. In general, it is very good idea to backup client’s root and also image in case if something will go wrong in process of customization or rollback is required. Approximate total backup size is about 3 GB.

Backup of client’s root directory can be created by following statement using tape archive command. Command for client’s image backup is introduced below.

$ sudo tar cjf /mnt/backup/<root>.tar.bz2 /opt/gislab/system/clients/desktop/root
$ sudo cp -a /opt/gislab/system/clients/desktop/image /mnt/backup/<image>

See Fig. 4.2 for clearer understanding.

../_images/backup.svg

Fig. 4.2 Recommended backup of client’s files.

Note

note Backup of client’s image file is not necessary because it can always be created by gislab-client-image command from particular GIS.lab client’s root. Why also this backup is useful will be introduced later.

When the recommended backups are created, it is time to start with customization.

See also

see See practical example of custom installation of latest GDAL version on GIS.lab client from source code.

Backups of client’s root and image is possible to recover if needed. First, current client’s root and image should be removed and afterwards, selected backup can be recovered, see commands below.

$ sudo rm -r /opt/gislab/system/clients/desktop/root
$ sudo rm -r /opt/gislab/system/clients/desktop/image

$ sudo tar xjf /mnt/backup/<root>.tar.bz2 -C /
$ sudo cp -a /mnt/backup/<image>/ /opt/gislab/system/clients/desktop/image

Using symbolic links

Violet diagram with blue line color called image in Fig. 4.2 containing gislab.img binary file and gislab-desktop.buildstamp in /opt/gislab/system/clients/desktop directory can be a directory or a symbolic link. By default it is a directory.

But it is very smart and handy to have more versions of image and just switching between them by symlink with nickname image and refer to particular directory with gislab.img and gislab-desktop.buildstamp files .

Note

note File gislab.img is a compressed client’s root directory.

Let’s say there are two different images for two different courses - beginner and advanced . They cause different customization of users.

When one wants to select desired image, following steps from /opt/gislab/system/clients/desktop directory should be used.

# get list of all saved versions of image
$ (cd /mnt/backup/; ls -la)
root-advanced
root-beginner
root-advanced.tar.bz2
root-beginner.tar.bz2
...
# remove current image and root
$ sudo rm -r image
$ sudo rm -r root
# switch to image for advanced course
$ sudo ln -s /mnt/backup/root-advanced image
# extract corresponding root from backup
$ sudo tar xjf /mnt/backup/root-advanced.tar.bz2 -C /

Then continue with creation of new user prepared for advanced course. See principle in Fig. 4.3.

../_images/image-symlink.svg

Fig. 4.3 Principle of using symlinks for effective customization.

Note

note When new image is set up on master, the clients are notified about new image and rebooted automatically after logout.

It is recommended to use Ansible to execute customization scripts directly from local controlling machine. See Executing customization scripts from Ansible example.

Important

imp GIS.lab master has to run during customization.

4.4. Boot loader

To customize GIS.lab Desktop client boot loader (see HTTP boot), create copy of boot loader source file http-boot/gislab-bootloader.ipxe and modify it as required. For more information about iPXE syntax see documentation. Than follow build process below.

Firstly, download iPXE source code.

$ git clone git://git.ipxe.org/ipxe.git && cd ipxe

Optionally checkout to version used by GIS.lab by typing

$ git checkout d644ad41f5a17315ab72f6ebeeecf895f7d41679

Finally build customized ISO image bin/ipxe.iso

$ cd src
$ make EMBED=CUSTOM-BOOT-LOADER-SOURCE-FILE.ipxe