Docker Deployment Guide

Running Webhookd in a Docker container is a highly recommended and common deployment strategy. It provides isolation, portability, and easy management.

Available Docker Images

Two main official images are provided on Docker Hub.

1. ncarlier/webhookd:latest (or slim) This is a lightweight, minimal image based on Alpine Linux. It contains just the webhookd binary and is suitable for running simple shell scripts.

2. ncarlier/webhookd:latest-distrib (or distrib) This image is also based on Alpine but includes additional tooling for more advanced use cases. It comes pre-installed with:

   • git
   • openssh-client
   • curl
   • jq
   • docker-cli
   • docker-cli-compose

   The distrib image is ideal if your scripts need to clone Git repositories, interact with the Docker daemon, or parse JSON with jq.

Basic Usage

To run a basic webhookd container, you need to mount a volume containing your scripts and publish the server's port.

Using docker run

docker run -d --name=webhookd \
  -p 8080:8080 \
  -v /path/to/your/scripts:/scripts \
  -e WHD_HOOK_SCRIPTS=/scripts \
  ncarlier/webhookd:latest

Using docker-compose

A docker-compose.yml file simplifies management. Here is a basic example:

version: "3.6"

services:
  webhookd:
    image: ncarlier/webhookd:latest
    container_name: webhookd
    restart: always
    ports:
      - "8080:8080"
    environment:
      - WHD_HOOK_SCRIPTS=/scripts
    volumes:
      - ./scripts:/scripts

Place this file in your project root and run docker-compose up -d.

Advanced: Deploying Scripts via Git

The distrib image includes a powerful feature that allows you to automatically clone a Git repository containing your scripts when the container starts. This is perfect for GitOps-style workflows where your webhook logic is version-controlled.

This feature is managed by the container's docker-entrypoint.sh script.

Configuration

To use this feature, you must set the following environment variables:

• WHD_SCRIPTS_GIT_URL: The SSH URL of the Git repository to clone (e.g., git@github.com:my-org/my-webhook-scripts.git). HTTPS is not supported.
• WHD_SCRIPTS_GIT_KEY: The path inside the container to the SSH private key required to clone the repository. This is typically a deploy key.
• WHD_HOOK_SCRIPTS (Optional): The directory inside the container where the repository will be cloned. Defaults to /opt/scripts-git.

Example with Docker Compose

This example demonstrates how to set up webhookd to clone scripts from a private Git repository.

1. Generate a deploy key:

   ssh-keygen -t ed25519 -f ./deploy_key -N ""

   Add the public key (deploy_key.pub) as a deploy key with read access to your GitHub/GitLab repository.

2. Create the docker-compose.yml:

   version: "3.6"
   
   services:
     webhookd:
       image: ncarlier/webhookd:latest-distrib # Must use the distrib image
       container_name: webhookd
       restart: always
       ports:
         - "8080:8080"
       environment:
         - WHD_SCRIPTS_GIT_URL=git@github.com:my-org/my-webhook-scripts.git
         - WHD_SCRIPTS_GIT_KEY=/etc/webhookd/deploy_key
       volumes:
         # Mount the private key into the container as a read-only file
         - ./deploy_key:/etc/webhookd/deploy_key:ro

When you run docker-compose up, the entrypoint script will use the provided SSH key to clone your repository into the container before starting the webhookd server. Your webhooks are now managed entirely through Git.