doil provides you with a simple way to create and manage development and testing environments for ILIAS. It will create and provision a docker container according to your requirements, pull the ILIAS version you want to use and even install it if possible. Also, doil provides you with a mail server wich collects all mails from your instances, so you can test the ILIAS emailing.
setup/conf/doil.conf
to your host namesetup/conf/doil.conf
setup/conf/doil.conf
to specify
where to place them, default is '/srv/instances'. Attention, paths with 'home' are not allowed here.sudo ./setup/install.sh
in order to install doildoil help
for available commands and further instructionsIf you use a doil version older than 20221110, we recommend completely removing an already installed doil from the system. This includes already installed instances. After that, you can proceed to the Installation section.
Removal Tips:
docker ps -a
shows all containersdocker rm <container_id>
removes container by id (ensure to delete all doil instances)docker images
shows all imagesdocker rmi <image_id>
remove image by id (ensure to delete all doil images)docker volume ls
shows all volumesdocker volume rm <volume_name>
remove volume by name (ensure to delete mail, proxy and salt)docker network prune
removes all networks without dependenciessudo rm -rf /etc/doil /usr/local/lib/doil /usr/local/share/doil /usr/local/bin/doil ~/.doil /var/log/doil
Otherwise, use the update script.
setup/conf/doil.conf
to specify
where to place them, default is '/srv/instances'. Attention, paths with 'home' are not allowed here. The update
will move all global instances to the set path.doil tries to use as little 3rd party software on the host system as possible, however doil needs Docker in order to work:
Additional dependencies, but these are installed automatically during setup.
The easiest way to fulfill the dependencies is Ubuntu 22.01, but it should also be possible with any other Linux installation.
Before starting make sure that you have set up your docker usergroup correctly
After you installed doil the basic system is ready to go. To get an instance of ILIAS running you simply need to do following steps:
~/Projects
doil create -e ilias7 -r ilias -b release_7 -p 7.4 -u
Don't worry, this will take a while. It creates and instance of ILIAS named ilias7
in your location from the repository ilias
(see doil repo:list
) with the known
branch release_7
and the PHP version 7.4
.
Be aware, there is no check wich php version matches on which ILIAS version.
After this job is finished you can start your instance with doil up ilias7
and head
to http://doil/ilias7/
to see your fresh ILIAS installation.
You can also get a quick overview on running doil instances by navigating with your
browser to 'http://doil'. If you have changed the host variable in the doil.conf file you
have to call 'http://
Each command for doil comes with its own help. If you struggle to use a command,
just add -h
or --help
to display the according help page. For example:
doil instances:create --help
. Use a simple doil
if you have no idea where to
start.
An instance is one environment for an installation of ILIAS. The purpose of doil is to make the management of these instances as simple as possible. The following commands are available:
doil create
(alias for doil instances:create
) creates a new instance in
the current working directorydoil up <instance_name>
starts an instance that you have created beforedoil path
prints the path to the location of the instancedoil ls
lists all available instancesdoil login <instance_name>
logs you into the container running the instancedoil down <instance_name>
stops an instance to free the resources it needsdoil delete <instance_name>
deletes an instance you do not need anymoredoil status
lists the current running doil instancesdoil exec <instance_name> <cmd>
executes a bash command inside the instanceSee doil instances:<command> --help
for more information
doil can use different ILIAS repositories to create instances. Per default,
the repository of the ILIAS society
will be used to pull the ILIAS code. If you want to use another repository to get
the ILIAS code, you can use commands from doil repo
to add and manage these
other repositories:
doil repo:add
will add a repository to the configurationdoil repo:update <repo_name>
will download the repo to doil's local cache or update
it if it is already downloadeddoil instances:create --repo REPO_NAME
will use the repo to create a new
instancedoil repo:delete <repo_name>
- removes a repositorydoil repo:list
- lists currently registered repositoriesSee doil repo:<command> --help
for more information
If you are running doil
on a system with multiple users you can manage your
repositories and instances globally for all user. For that we implemented several
helper and flags.
The user who installed doil on the machine is already registered at doil. To add
another user simply use doil system:user add <username>
. You can manage the users
with following commands:
doil user:add <username>
adds a user (needs sudo privileges)doil user:delete <username>
deletes a user (needs sudo privileges)doil user:list
lists the available usersSee doil user:<command> --help
for more information
--global
flagMost commands in doil come with a --global
flag. For instance if you created an
ILIAS instance with doil create --global
the instance will then be available to
all registered users. You can start the instance with doil up <instance> --global
.
If you want to create an instance with a global repository you have to use the flag
-u|--use-global-repo
, e.g, doil create -r ilias -u
Following commands come with the --global
flag:
doil instances
doil instances:create
doil instances:up
doil instances:down
doil instances:delete
doil instances:apply
doil instances:path
doil instances:login
doil instances:exec
doil repo
doil repo:add
doil repo:delete
doil repo:update
doil pack
doil pack:import
doil pack:export
You can also create global instances with private repositories and vice versa.
doil lets you transfer the data of one installation of ILIAS ot another. Instances build with doil (instances from version >=1.1) are able to be exported.
doil pack:export
exports an instancedoil pack:import
imports an instanceSee doil pack:<command> --help
for more information
To start doil:pack export
via cronjob you need two additional parameters.
The first parameter (-T or --no-term) is attached to the doil commando.
It ensures that docker can run without a terminal.
The second parameter (-c or --cron) is required for the pack:export
command.
It ensures that the console command does not open an additional terminal.
The complete call then looks like this:
doil -T pack:export -c <instance_name> [-g]
Most of the commands come with a --quiet
flag to omit the log messages.
However, these logs are not lost, they are stored in /var/log/doil/doil.log
and in /var/log/doil/salt.log
. You may
want to add a rotation to this logfile.
There may be a problem with the ~/.docker directory. It may happen that after a reboot the file permissions and the owner of the folder have to be adjusted again. If this is the case for you, you can also consider creating a startup script that automatically adjusts this folder every time the system starts.
If the proxy server reports 'Minion did not return' during the install/update process, please abort the process and start it again.
Sometimes it is possible that the proxy server doesn't accept the configuration. This results
in a 404 when heading to your instance after using doil up
. To fix this you just need to restart
the proxy server with doil proxy:restart
. If the 404 still occurs restart your instance
with doil down
and doil up
.
While creating an instance or using doil apply
it is possible that there will be a "Key not ready"
loop. This loop tries to find a certain key in the salt main server. To fix this issue let the loop
run and open a new terminal and do following steps:
doil salt:prune
doil salt:restart
doil down <instance_name>
doil up <instance_name>
Usually the loop will then resolve itself and the creation or apply process will continue. If the loop continues then there might be a problem with the public key of the salt main server. To fix this do following steps:
doil login <instance_name>
rm /etc/salt/pki/minion/minion_master.pub
exit
doil down <instance_name>
doil up <instance_name>
doil uses SaltStack to provision and maintain the instances. Docker is only used as a light weight and widely available VM-like technology to run sufficiently isolated linux environments. SaltStack uses an architecture where one master acts as a central control server. doil runs this master in a dedicated container. The instances then are deployed into separate containers as minions that are controlled and provisioned by the master. Required folders are mounted in the users filesystem via Dockers volumes and can be accessed from the host system.
doil comes with some helpers which are useful if you want to hack on doil:
doil -V|--version
displays the versiondoil
displays the main help pageAlso, there is a script to uninstall doil in the doil repo. If you have already deleted the folder easily clone it again from doil.
Cd into the cloned folder and execute the script.
sudo ./setup/uninstall.sh
The script will ask you if you want to remove doil completely from your system or if you want to keep your instances, images ...
To be able to dive deeper into the inner workings of doil or customize it to fit your workflow or requirements, doil provides commands to tamper with the saltstack in the background. These commands will not be required by ordinary users, so make sure to understand what you are doing.
doil salt:login
logs the user into the main salt serverdoil salt:prune
prunes the main salt serverdoil salt:start
starts the salt main serverdoil salt:stop
stops the salt main serverdoil salt:restart
restarts the salt main serverdoil salt:states
to list the available statesSee doil salt:<command> --help
for more information
To be able to dive deeper into the inner workings of doil or customize it to fit your workflow or requirements, doil provides commands to tamper with the proxy in the background. These commands will not be required by ordinary users, so make sure to understand what you are doing.
doil proxy:login
logs the user into the proxy serverdoil proxy:prune
removes the configuration of the proxy serverdoil proxy:start
starts the proxy serverdoil proxy:stop
stops the proxy serverdoil proxy:restart
restarts the proxy serverdoil proxy:reload
reloads the configurationSee doil proxy:<command> --help
for more information
There is the state 'proxy-enable-https' to make the proxy accessible via https.
This is done by certbot.
In order for this state to run successfully, it is important that the proxy is already accessible from the Internet and the DNS entries are set.
To execute the state you have to log in to the salt master using doil salt:login
. The following command is then executed there:
salt 'doil.proxy' state.highstate saltenv=proxy-enable-https pillar='{"email": "<your_email>", "domain": "<your_domain>"}'
If the state has run successfully, the current status of the proxy still needs to be committed. To do this, leave the
salt master again with ctrl-d
and execute the following command:
docker commit doil_proxy doil_proxy:stable
The state also sets up a cron job that regularly renews the certificates.
After that please ensure to run doil apply <instance_name> enable-https
on each doil ILIAS instance,
so https take effect in ILIAS.
The mailserver is available at http://doil/mails
with following
login data:
You can change the password in the doil config file setup/conf/doil.conf
.
Before installing doil change the default password to your password.
If doil is already installed you can change the password by doil mail:change-password <password>
.
Please ensure you also update the password in your actual installed
doil config /etc/doil/doil.conf
, so you don't have to set the passwort again after a doil update.
Every minion sends all E-Mails to this mailserver.
To be able to dive deeper into the inner workings of doil or customize it to fit your workflow or requirements, doil provides commands to tamper with the mailserver in the background. These commands will not be required by ordinary users, so make sure to understand what you are doing.
doil mail:change-password
changes the default password for roundcubedoil mail:login
logs the user into the mail serverdoil mail:start
starts the mail serverdoil mail:stop
stops the mail serverdoil mail:restart
restarts the mail serverdoil provides two options to enable xdebug for the given instance.
Option 1: An instance can be created with the '-x' flag, or alternatively
in interactive mode you will be asked to install xdebug.
On the command line it could look like this:
doil create -e ilias7 -r ilias -b release_7 -p 7.4 -u -x
Option 2: You can apply a state to an already existing instance.
To activate xdebug use the following command:
doil apply <instance_name> enable-xdebug
Alternatively, you can type doil apply <instance_name>
and select
'enable-xdebug' from the list.
You can turn off xdebug again in the same way:
doil apply <instance_name> disable-xdebug
xdebug listens to port 9000 when activated. Now the client has to be set up. Unfortunately, I can only present the configuration of PHP-Storm here as an example. But it should work similarly for other editors.
Now, reload the ILIAS page to debug. PHP-Storm should inform you about an incomming debug connection.
Contributions to doil are very welcome!
If doil saved your precious time and brain power, please consider supporting doil: