A light image of adnanh's webhook which is able to access the Docker host and control containers. This image is based upon TheCatLady's webhook docker image. In addition to some minor tweaks this image has access to the docker host and therefore is able to execute Docker commands on the host. This is possible by exposing the docker socket and adding packets for docker compose and the docker cli.

Table of Contents

• Security Concerns
• How to Use
  • Docker Compose
  • Updating
• Parameters
• Configuring Hooks

Security Concerns

In order to run docker commands inside the container and actually execute them on the docker host, the docker socket of the host needs to be exposed. While this allows to execute docker commands (e. g. for a CI/CD workflow) triggered by a webhook, it also poses a security risk. The risk involves that a container which has access to the docker socket may be able to get root access to the host. In order to lessen this security threat a Docker Socket Proxy can be used (e. g. Tecnativa's Docker Socket Proxy).

Also, if you further want to inform yourself about the advantages and risks of executing docker commands inside a docker conatainer and access the docker host via the Docker socket, take a look for example at this post from Jérôme Petazzoni or this post from Tom Gregory.

How to use

Docker images are available from Docker Hub and GitHub Container Registry (GHCR).

Docker Compose (example)

Add the following volume and service definitions to a docker-compose.yml file:

services:
  webhook:
    image: heg0dmsk/webhook-docker
    container_name: webhook
    command: -verbose -hooks=hooks.json -hotreload
        environment:
      - TZ=Europe/Berlin #optional
    volumes:
      - /path/to/appdata/config:/config:ro
      # exposing the docker socket, needed to access the docker host
      - /var/run/docker.sock:/var/run/docker.sock 
    ports:
      - 9000:9000
    restart: always

Then, run the following command from the directory containing your docker-compose.yml file:

docker-compose up -d

Updating

The process to update the container when a new image is available is dependent on how you set it up initially. If you initially used Docker Compose, run the following commands from the directory containing your docker-compose.yml file:

# Pull latest version of the images specified in the docker-compose.yml file
docker-compose pull 

# Redeploy
docker-compose up -d

# Remove old dangling Images
docker image prune

Parameters

The container image is configured using the following parameters passed at runtime:

Parameter	Symbol	Example	Description
Volume	-v	/path/to/appdata/config:/config:ro	Container data directory (mounted as read-only); your JSON/YAML hook definition file should be placed in this folder (Replace /path/to/appdata/config with the desired path on your host)
Volume	-v	/var/run/docker.sock:/var/run/docker.sock	Exposing the docker socket, needed to access the docker host
Port	-p	9000:9000	Expose port 9000 (Necessary unless only accessing webhook via other containers in the same Docker network)
Restart Policy	--restart	recommended always	Container restart policy
Command		-verbose -hooks=/config/hooks.json -hotreload	webhook parameters; replace hooks.json with the name of your JSON/YAML hook definition file, and add/modify/remove arguments to suit your needs (Can omit if using this exact configuration; otherwise, all parameters must be specified, not just those modified)
environment	-e	TZ=Europe/Berlin	Specifcies timezone of the container, Look up timezones here

Configuring Hooks

See adnanh/webhook for documentation on how to define hooks.