linci

Setting up a server

To setup a linci server you need a Ubuntu server/VM/container with minimal resources. Add to that the resources needed for the builds you want to run. Ubuntu is recomended and tested, Debian should be OK. There is nothing in linci that is specific to Debian, its packaged as a .deb which (currently) contains no binary code and depends on common Linux applications. It runs happily on raspbian and a raspberry pi.

Dependencies

linci's dependencies in the deb file are ngircd, ii, gawk, openssl, openssh-server, task-spooler with the exception of gawk its not too complicated to work around each of those deps if they cause you issues.

linci is very much dependent on bash, gawk is used for reading config files.

Install

Install the deb with dpkg -i linci-*.deb, or setup apt as per the instructions here. This will install the linci application, create directories, and create the ci user, which is the user that typically runs linci commands.

Boot

On boot its recommeneded to wipe /tmp/linci/ if your distro does not do this already, and to start ii and tsp.

ii - the interface to IRC that linci uses to send messages.
tsp - the task-spooler demon, tsp is used to limit the number of concurrent jobs linci is running.

Boot scripts are found in /usr/share/linci/init A simple boot procedure is to add this to /etc/rc.local

/usr/share/linci/init/init-tmp-linci.sh
su - ci /usr/share/linci/init/init-ii.sh &
su - ci /usr/share/linci/init/init-tsp.sh &

IRC

Setting up an IRCd server is a case of booting the ngircd deamon that is installed with linci. If you don't want to host an IRCd you can use freenode by configuring /etc/linci/irc.conf By default linci sends all status messages to IRC, and if IRC is down, builds hang. The idea here is that linci's main job is to run builds and tell you when they break. If you don't fancy IRC you can it by setting export NOTIFY_IRC_ENABLE=false in irc.conf

Email

Email is sent by calling mailx, by default, this will dump mail in a file somewhere locally. Setting up postfix od ssmtp are probably the simplest ways to get up and running with email notifications. Setting export NOTIFY_MAIL_ENABLE=true in mail.conf will enable sending of emails. You should set a default recipient, individual jobs or environments can override this value. There is no clever stuff to send emails to the person that did the submit.

STOMP

Via xtomp-cat linci can send messages to a STOMP message broker, this enables integrating success or failure messages with other systems.

Hooks

Other types of notification can be added by implementing a script in /var/linci/hooks/. Included notifications are implemented as bash scripts, so serve as examples of how to add notification hooks.

linci shell

If you prefer the linci shell for the ci user add this to the bottom of /home/ci/.bashrc

# replace current shell with the linci one
test -z "$NOLINCI" && exec linci shell

This is not done by default because it has side effects for scripts that presume a login shell is plain bash. i.e. it may break things that do bash -l.

File System

Linci tries to maintain Linux best practices for use of the file system. Everything is a file, it keeps all variable data in /var/linci, static config in /etc/linci, and code (non binary) in /usr/share/linci, it should be ok to run with ro mounted /usr and /etc. Paths are not configurable, i.e. its not suitable for flatpack or snaps, it is happy in chroots and LXC containers. Data and config are line based text files so play nicely with VCS systems such as git, its recommended to keep /var/linci/config under version control. Nothing is required in $HOME. Linci supports init freedom.