zackprod/puller-dockerhub repository overview

⁠PULLER DOCKERHUB

A lightweight HTTP API to automate CI/CD using Docker Hub .

⁠📋 Table of Contents

• 🚀 What Is Puller?⁠
• ✨ Key Features⁠
• 🚀 Quick Start⁠
• ⚙️ Configuration⁠
  • Environment Variables⁠
  • Compose Setup⁠
• 📖 Usage⁠
  • Trigger via HTTP⁠
  • 🔗 Integrate with Docker Hub⁠
• 🛠️ Health & Logging⁠
• 🐞 Troubleshooting⁠
• 🤝 Contributing⁠
• 📄 License⁠
• 📬 Contact⁠

⁠🚀 What Is Puller?

Puller is a minimal HTTP API service that listens for Docker Hub webhook payloads and, pulls and redeploys a specified container.

It's designed to be lightweight, easy to configure, and suitable for use in CI/CD pipelines.

This lets you automatically redeploy containers whenever you push a new image tag to Docker Hub, without manual intervention.

⁠✨ Key Features

• Automatic Pull & Deploy
  Executes docker pull and docker-compose up on-demand.
• Webhook Listener
  Accepts Docker Hub webhook POSTs and parses the payload for image and tag.
• Configurable
  Control ports, retry attempts, and service names via environment variables.
• Lightweight
  Small memory footprint and simple dependencies.
• Secure by Default
  Runs with read-only Docker socket and minimal privileges.

⁠🚀 Quick Start

1. Clone & Deploy

   git clone https://github.com/ehzack/puller-dockerhub.git
   cd puller-dockerhub
   docker-compose up -d
   

   Copy

2. Configure Webhook on Docker Hub
   See Integrate with Docker Hub⁠ below.

3. Push a New Tag

   docker tag my-app:latest youruser/my-app:release-1.0
   docker push youruser/my-app:release-1.0
   

   Copy

   Puller will automatically pull and redeploy your container.

⁠⚙️ Configuration

⁠Environment Variables

⁠Compose Setup

version: "3.8"
services:
  puller:
    image: ehzack/puller-dockerhub:latest
    restart: always
    ports:
      - "${SERVER_PORT:-4999}:4999"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      SERVER_PORT: 4999
      LOG_MAX_SIZE: 3 # in MB
      LOG_MAX_FILES: 3

⁠📖 Usage

⁠Trigger via HTTP

You can manually trigger a pull & deploy:

curl -X POST "http://<HOST>:<PORT>/trigger"      -H "Content-Type: application/json"      -d '{
       "image": "youruser/my-app:latest",
       "composeService": "web"
     }'

• image: Full image reference (<repo>:<tag>).
• composeService: (Optional) Overrides COMPOSE_SERVICE env var.

⁠🔗 Integrate with Docker Hub

1. Add Webhook
   • Go to your Docker Hub repo ▶︎ Settings ▶︎ Webhooks.
   • Click Add Webhook, set the URL to:

     http://<PULLER_HOST>:<PULLER_PORT>/trigger?path=$path$&container_name=$container_name
     

     Copy

Query Parameters:

• $path: The location of your docker-compose.yml file (Example: /home/user/app/docker-compose.yml)
• $container_name: The name of the container you want to restart (Example: my-web-app)

Example URL:

• http://localhost:4999/trigger?path=/home/user/app/docker-compose.yml&container_name=web-app⁠

1. Configure Compose Service
   Ensure your docker-compose.yml defines the service you want to restart:

   version: "3.8"
   services:
     web:
       image: youruser/my-app:latest
       # ...
   

   Copy

2. Push New Image
   Every docker push will send a webhook to Puller. It will:

   1. Parse the payload for repository and push_data.tag.
   2. Run docker pull youruser/my-app:<tag>.
   3. Execute docker-compose up -d web.

⁠🛠️ Health & Logging

• Health Endpoint:
  GET /health returns 200 OK if service is healthy.
• Logs:
  Stream logs via Docker:

  docker logs -f puller-dockerhub_puller_1
  

  Copy

⁠🐞 Troubleshooting

• Socket Permission Denied

  sudo chmod 660 /var/run/docker.sock
  sudo usermod -aG docker $(whoami)
  

  Copy
• Unexpected Payload
  Ensure Docker Hub webhook is configured with application/json content type.
• Service Not Restarting
  Confirm COMPOSE_SERVICE matches your service name in docker-compose.yml.

⁠🤝 Contributing

We welcome your improvements and bug fixes! Please see CONTRIBUTING.md⁠.

⁠📄 License

This project is licensed under the MIT License. See LICENSE⁠.

⁠📬 Contact

• Author: Zack
• GitHub: ehzack/puller-dockerhub⁠