Installing Additional Modules in the Icinga Web 2 Docker Container

The Docker images we provide for both Icinga 2 and Icinga Web 2 already contain quite a number of modules. For example, the Icinga Web 2 image contains all the Web modules developed by us. But one of the main benefits of Icinga is extensibility, so you might want to use more than what is already included. This might be some third-party module or a custom in-house module. This blog post will take the map module as an example to show how it can be installed in the Icinga Web 2 container using two possible methods.

Option #1: Install to the /data volume

This is probably the easier option if you just want to install a module in a single container. As per the instructions, the Icinga Web 2 image expects a volume mounted at /data, you can just install the module to that volume and configure Icinga Web 2 to use it from there. This can be done with the following steps:

• Download the module and unpack it to the data volume so that it appears at /data/extra-modules/map within the container.
• If you use the icingaweb.enabledModules environment variable:
  • Ensure that map is added to that variable before the container is restarted the next time so that it won’t disable the module.
  • Manually enable the module from the non-standard path:
    docker exec my-web-container ln -s /data/extra-modules/map /etc/icingaweb2/enabledModules/
• If you don’t use the icingaweb.enabledModules environment variable:
  • Restart the container with the additional environment variable:
    icingaweb.config.global.module_path=/usr/share/icingaweb2/modules:/data/extra-modules
  • You can now enable the module from within Icinga Web 2 as you are used to.

This method allows you to independently update Icinga Web 2 by simply restarting the container from a newer image and the module by just copying a newer version to the data volume.

Option #2: Build a custom image

There is a second and slightly more advanced option: you can also build your custom Icinga Web 2 Docker image based on the image we publish oh Docker Hub and include any modules you like. This option might better fit your needs if you already deploy your applications as custom Docker images and therefore already have the infrastructure for automatically building and deploying these in place, or maybe you want to deploy the same modules to multiple Icinga Web 2 installation without doing the steps from the first option on each instance.

To build your own Docker image, you have to write your own Dockerfile. The following is an example that you can use as a starting point.

# Use a temporary container to obtain the module. This allows to use additional
# tools in this container without having to install them in the final
# container, which would needlessly increase its size.
FROM alpine/git AS build
# Specify the version of the map module to download.
ARG map_version=1.1.0
# Clone the map Git repository and change to its working directory.
RUN git clone https://github.com/nbuchwitz/icingaweb2-module-map.git /src/icingaweb2-module-map
WORKDIR /src/icingaweb2-module-map
# Prepare a directory to export the module.
RUN mkdir /build
# Let Git export the desired version as a tar file and immediately extract this
# file to the /build directory so that the module ends up in /build/map. This
# additional step using git archive is done so that the module is exported
# without the .git directory as this is not needed in the final image.
RUN git archive --forma=tar --prefix=map/ v${map_version} | tar -xC /build

# Now create the final image using the latest Icinga Web 2 image as a base.
FROM icinga/icingaweb2:latest
# And copy the module to the default module path in that container.
COPY --from=build /build/map /usr/share/icingaweb2/modules/map

Just save this into a file called Dockerfile in a new directory and run the command docker build -t custom-icingaweb2 . (the trailing dot is part of the command) to build the image. You can now use the resulting custom-icingaweb2 image just like you would use the official icinga/icingaweb2 image.

Note that with this option, you have to rebuild and deploy the image each time you want to update either Icinga Web 2 or any of the additional modules installed.