Skip to content

Install Update

Jump to bottom
Daniel Weise edited this page Aug 7, 2025 · 11 revisions

Dependencies

doil tries to use as little 3rd party software on the host system as possible, however doil needs Docker in order to work:

  • docker (follow this instructions depending on your os to install docker), if you have installed docker by your package manager ensure that docker-buildx-plugin and docker-compose-plugin are available and installed and also executable by your user.
  • make sure that you have set up your docker usergroup correctly
  • git
  • .ssh folder in your home directory. doil will mount it into the container. doil needs this to give you access to your private git repositories that may be used.

Additional dependencies, but these are installed automatically inside a container during setup.

  • php version => 7.4
  • php*.*-zip
  • php*.*-dom
  • composer version = depending on installed php version
  • symfony/console
  • symfony/filesystem
  • symfony/process
  • pimple
  • ext/posix
  • ext/zip
  • ext-openssl
  • psr/log
  • monolog/monolog

The easiest way to fulfill the dependencies is Ubuntu 22.01, but it should also be possible with any other Linux installation.

Installation

Doil comes with some dependencies that must be fulfilled before installation. Please have a look at the Dependencies section on this page.
In addition, the installation of doil will fail if artifacts from a previously installed doil version are still present. To prevent this, the uninstall script can be called before installation. Please have a look at the Uninstall section on this page.

Please follow these steps to install doil:

mkdir doil | curl -L $(curl -s https://api.github.com/repos/conceptsandtraining/doil/releases/latest | grep tarball_url | cut -d "\"" -f4) | tar xz -C doil --strip-components=1
  • adjust the settings in doil/setup/conf/doil.conf to your needs
    • host - set this if to your hostname if you use doil on a remote host
    • mail_password - change this for a more secure password
    • global_instances_path - doil will install all global instances to this path. Attention, paths with 'home' are not allowed here.
nano doil/setup/conf/doil.conf
  • install doil
cd doil && sudo ./setup/install.sh
  • remove repo
cd .. && rm -rf doil
  • run doil
doil

Update

If you use a doil version older than 20221110, we recommend completely removing an already installed doil from the system. This includes already installed instances. Please have a look at Removal-Tips section on this page. After that, you can proceed to the Installation section.

Otherwise, use the update script.

mkdir doil | curl -L $(curl -s https://api.github.com/repos/conceptsandtraining/doil/releases/latest | grep tarball_url | cut -d "\"" -f4) | tar xz -C doil --strip-components=1
  • adjust the settings in doil/setup/conf/doil.conf to your needs
    • host - set this if to your hostname if you use doil on a remote host
    • mail_password - change this for a more secure password
    • global_instances_path - doil will install all global instances to this path. Attention, paths with 'home' are not allowed here.
nano doil/setup/conf/doil.conf
  • update doil
cd doil && sudo ./setup/update.sh
  • remove repo
cd .. && rm -rf doil
  • run doil
doil

Uninstall doil

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

Removal-Tips

  • docker ps -a shows all containers
  • docker rm <container_id> removes container by id (ensure to delete all doil instances)
  • docker images shows all images
  • docker rmi <image_id> remove image by id (ensure to delete all doil images)
  • docker volume ls shows all volumes
  • docker volume rm <volume_name> remove volume by name (ensure to delete mail, proxy and salt)
  • docker network prune removes all networks without dependencies
  • sudo rm -rf /etc/doil /usr/local/lib/doil /usr/local/share/doil /usr/local/bin/doil ~/.doil /var/log/doil
  • remove the instances folders or if you placed all instances in one folder remove the whole folder

Config

You can find the Doil Config here /etc/doil/doil.conf. Currently, changes to doil.conf are only taken into account when an update is applied.

  • host
    • type: string
    • default: doil
    • explanation: Name under which the server will be accessible, i.e http://doil.
  • allowed_hosts
    • type: bool/array
    • default: false
    • explanation: A list of valid hosts which is used to validate the HTTP_HOST header of incoming web requests. If the host header does not match any of the allowed hosts, the request is rejected. I.e. ["192.168.22.11", "192.168.33.11"]
  • https_proxy
    • type: bool
    • default: false
    • explanation: If 'true' the Doil instances are only accessible with https.
  • mail_password
    • type: string
    • default: ilias
    • explanation: Sets the password for the Doil Roundcube instance.
  • global_instances_path
    • type: string
    • default: /srv/instances
    • explanation: Doil instances created with the -g (--global) flag will end up in this directory.
  • enable_keycloak
    • type: bool
    • default: false
    • explanation: If 'true' the Doil-Keycloak instance is created and/or activated.
  • keycloak_hostname
    • type: string
    • default: http://doil/keycloak
    • explanation: The complete URL to the Doil Keycloak instance.
  • keycloak_new_admin_password
    • type: string
    • default: admin
    • explanation: Password for the Doil Keycloak instance. On initial installation, it must be the same as 'keycloak_old_admin_password'.
  • keycloak_old_admin_password. In case of an update, a new password can optionally be assigned here.
    • type: string
    • default: admin
    • explanation: Password for the Doil Keycloak instance. On initial installation, it must be the same as 'keycloak_new_admin_password'. When updating, the current password must always be entered here.
  • keycloak_db_username
    • type: string
    • default: admin
    • explanation: Username for the Keycloak database.
  • keycloak_db_password
    • type: string
    • default: admin
    • explanation: Password for the Keycloak database.
  • update_token
    • type: bool/string
    • deafult: false
    • explanation: This option is only available to CaT internal users. Automatic updates are enabled once a token is specified. External users should always leave this option set to 'false'.
  • git_private_ssh_key_path
    • type: bool/string
    • initial: false
    • explanation: Absolute path to a file containing a private SSH key that has access to private Git repositories used in Doil.
    • attention: The SSH keys must be specified. If you don't already have an SSH key for Github, you can create one using these instructions.
    • example: git_private_ssh_key_path=/home/foobar/.ssh/id_rsa
  • git_public_ssh_key_path
    • type: bool/string
    • initial: false
    • explanation: Absolute path to a file containing the corresponding public SSH key to 'git_private_ssh_key_path'.
    • attention: The SSH keys must be specified. If you don't already have an SSH key for Github, you can create one using these instructions.
    • example: git_private_ssh_key_path=/home/foobar/.ssh/id_rsa.pub

If doil saved your precious time and brain power, please consider supporting doil:

  • Buy Laura (initial creator) 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 Daniel 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.

Clone this wiki locally