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.
- download and unpack the latest release
- execute
sudo ./install.sh
in order to install doil - you can remove the downloaded folder afterwards
- check
doil help
for available commands and further instructions
If you alread installed doil you can easily update with following steps:
- download and unpack the latest release
- execute
sudo ./update.sh
in order to update doil - you can remove the downloaded folder afterwards
doil tries to use as little 3rd party software on the host system as possible. However doil needs Docker in order to work:
- docker version >= 19.03
- docker-compose version >= 1.25.0
- zip
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:
- Head to a folder where you want to store your project. Usually
~/Projects
- Enter following command:
doil create -n ilias -gr ilias -b release_7 -p 7.4
Don't worry, this will take a while. It creates and instance of ILIAS named ilias
in your location from the repository ilias
(see doil repo:list
) with the known
branch release_7
and the PHP version 7.4
.
After this job is finished you can start your instance with doil up ilias
and head
to http://doil/ilias/
to see your fresh ILIAS installation.
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 doil --help
if you have no idea where too
start.
An instance is one environment for and 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 fordoil instances:create
) creates a new instance in the current working directorydoil up
starts an instance that you have created beforedoil cd
switches the current working directoryto the location of the instancedoil ls
lists all available instancesdoil login
logs you into the container running the instancedoil down
stops an instance to free the ressources it needsdoil rm
deletes an instance you do not need anymoredoil apply
applys a certain state to the instancedoil ps
lists the current running doil instances
See doil instances --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
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
- removes a repositorydoil repo:list
- lists currently registered repositories
See doil repo --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 system:user add <username>
adds a userdoil system:user delete <username>
deletes a userdoil system:user list
lists the available users
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
-gr|--global-repo
, e.g, doil create -gr ilias
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:cd
doil instances:login
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 instance
See doil pack --help
for more information
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.log
. You may
want to add a rotation to this logfile.
- doil was developed and tested on debian and ubuntu systems. It might run on other linux based platforms but there is no guarantee
- due to network restrictions on MacOS doil can only operate run one instance at once. Though it's possible to create as many environments as you want
- doil works on Windows with the WSL enabled. Due to network restrictions you
need to change the host to
localhost
via the doil proxy settings:doil system:proxy host localhost
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 system: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 system:salt prune
doil system:salt restart
doil down ${instance}
doil up ${instance}
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}
rm /var/lib/salt/pki/minion/minion_master.pub
exit
doil down ${instance}
doil up ${instance}
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 usefull if you want to hack on doil:
doil system:deinstall
will be remove doil from your systemdoil system:version
displays the versiondoil system:help
displays the main help page
See doil system --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 saltstack in the background. These commands will not be required by ordinary users, so make sure to understand what you are doing.
doil system:salt login
logs the user into the main salt serverdoil system:salt prune
prunes the main salt serverdoil system:salt start
starts the salt main serverdoil system:salt stop
stops the salt main serverdoil system:salt restart
restarts the salt main serverdoil system:salt states
to list the available states
See doil system:salt --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 system:proxy login
logs the user into the proxy serverdoil system:proxy prune
removes the configuration of the proxy serverdoil system:proxy start
starts the proxy serverdoil system:proxy stop
stops the proxy serverdoil system:proxy restart
restarts the proxy serverdoil system:proxy reload
reloads the configurationdoil system:proxy host <host>
changes the default host
See doil system:proxy --help
for more information
Contributions to doil are very welcome!
- Have a look into the Contributor's Guide before you start.
- If you face any issues or want to suggest a feature or improvement, open an issue.
- Make sure to understand that this is a voluntary offer which requires time, passion and effort and does not guarantee anything to anyone. Be gentle.
If doil saved your precious time and brain power, please consider supporting doil:
- Buy Laura a coffee and tell her about your doil experiences if you meet her somewhere.
- Star the project and share it. If you blog, please share your experience of using this software.
- Look into CaT's products and services and consider to place an order or hire us.
- Reach out to Laura and Richard if you have requirements, ideas or questions that you don't want to discuss publicly.
- Reach out to Richard if you need more support than we can offer for free or want to get involved with doil in other ways.