Usage

Help

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.

Instances

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 directory
• doil up <instance_name> starts an instance that you have created before
• doil path prints the path to the location of the instance
• doil ls lists all available instances
• doil login <instance_name> logs you into the container running the instance
• doil down <instance_name> stops an instance to free the resources it needs
• sudo doil delete <instance_name> deletes an instance you do not need anymore (needs sudo privileges)
• doil status lists the current running doil instances
• doil exec <instance_name> <cmd> executes a bash command inside the instance
• doil csp <instance_name> -r <csp_rules> add csp rules for one instance or for all instances with the -a flag

See doil instances:<command> --help for more information

Repository

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 configuration
• doil repo:update <repo_name> will download the repo to doil's local cache or update it if it is already downloaded
• doil instances:create --repo REPO_NAME will use the repo to create a new instance
• doil repo:delete <repo_name> - removes a repository
• doil repo:list - lists currently registered repositories

See doil repo:<command> --help for more information

Global User Support

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.

Adding user to doil

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 users

See doil user:<command> --help for more information

The --global flag

Most 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.

Pack

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 instance
• doil pack:import imports an instance

See 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]

Quietmode and Logs

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.

SaltStack

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.

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 server
• doil salt:prune prunes the main salt server
• doil salt:start starts the salt main server
• doil salt:stop stops the salt main server
• doil salt:restart restarts the salt main server
• doil salt:states to list the available states

See doil salt:<command> --help for more information

Proxy Server

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 server
• doil proxy:prune removes the configuration of the proxy server
• doil proxy:start starts the proxy server
• doil proxy:stop stops the proxy server
• doil proxy:restart restarts the proxy server
• doil proxy:reload reloads the configuration

See doil proxy:<command> --help for more information

Https

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.

Mail Server

The mailserver is available at http://doil/mails with following login data:

• User: www-data
• Password: ilias

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 roundcube
• doil mail:login logs the user into the mail server
• doil mail:start starts the mail server
• doil mail:stop stops the mail server
• doil mail:restart restarts the mail server

Keycloak Server

The Keycloak server is an identity provider that allows you to log in to all ILIAS instances managed by doil with one password.
This requires some settings in the doil.conf file. 'doil.conf' can be found under setup/conf/doil.conf. The adjustments must be made before an update/install.

The following settings are available:

• enable_keycloak=[true/false] decides whether keycloak is installed during an update/install [default:false]
• keycloak_hostname=http://doil/keycloak keycloak url, please pay attention to https/http
• keycloak_new_admin_password=12345 admin password
• keycloak_old_admin_password=12345 If the password is changed during an update, the old password must be entered here. Please make sure to adjust it after the update.
• keycloak_db_username=admin database user name
• keycloak_db_password=admin database user password

If you use keycloak, the salt state enable-saml must be called for existing ILIAS instances. This is done using the 'doil apply <instance_name>' command.
Newly created instances check whether keycloak is enabled and set up the instance directly.

Create a user in Keycloak

• select tab 'users' from left menu
• click 'Add user'
• enter a Username
• enter an Email
• click 'Create'

Cretae a user in ILIAS

• select tab 'Administration' from left menu
• select 'Users and Roles'
• select 'User Management'
• click 'Add User'
• fill in the required fields (username must be the same as in keycloak)
• set 'External Account' to the same email as in keycloak

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 keycloak in the background. These commands will not be required by ordinary users, so make sure to understand what you are doing.

• doil keycloak:login logs the user into the keycloak server
• doil keycloak:up starts the keycloak server
• doil keycloak:down stops the keycloak server
• doil keycloak:restart restarts the keycloak server

See doil keycloak:<command> --help for more information

xdedug

doil 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.

Necessary PHP-Storm plugins:

• PHP Docker
• PHP Remote

PHP-Storm settings

• it is best to open the doil instance root directory in PHP-Storm.
• under Settings->PHP->CLI Interpreter: add a new interpreter (on the 3 dots and then in the pop-up on +)
• select "From Docker, Vagrant..." and then select "Docker Compose".
• if you already have the doil instance root open in PHP-Storm, it automatically selects the docker-compose.yml
• select the doil instance name under Service (e.g. ilias7) and click "OK".
• click on the reload icon under General PHP executable and the warnings should disappear. Then click 'OK' to close the pop-ups.
• click "Apply" and "OK"
• set a breakpoint somewhere that should be reached
• click on the "Listen for PHP Debug Connections" in the upper right corner

Browser settings

• install 'Xdebug helper' as a browser extension
• activate the little bug in the address bar

Now, reload the ILIAS page to debug. PHP-Storm should inform you about an incomming debug connection.

Prevent Super Globals Replacement

Since ILIAS version 8 it is necessary to set the setting 'prevent_super_global_replacement = 1' in the client.ini.php. doil offers a state for this.

doil apply <instance_name> prevent-super-global-replacement

As of doil version 20241113, doil applies this state independently to newly created instances.