PHPackages                             pipestream/light-hook-deploy - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. pipestream/light-hook-deploy

ActiveProject

pipestream/light-hook-deploy
============================

Light Hook Deploy service for automated deployments using webhooks.

2.0.1(1y ago)446↓100%Apache-2.0PHPPHP &gt;=8.2

Since Aug 8Pushed 1y ago1 watchersCompare

[ Source](https://github.com/Gparrac/light_hook_deploy)[ Packagist](https://packagist.org/packages/pipestream/light-hook-deploy)[ RSS](/packages/pipestream-light-hook-deploy/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (6)Versions (7)Used By (0)

🚀 Light Hook Deploy
===================

[](#--light-hook-deploy)

Introduction 🌟
--------------

[](#introduction-)

**Light Hook Deploy** is a microservice designed to streamline **automated deployments** using webhooks. This service is not meant to replace comprehensive tools like **Jenkins**, **CodeDeploy**, **Azure Pipelines**, or other CI/CD methods. Instead, it offers a **lightweight**, **easily configurable** solution for environments that need automated deployment without the overhead of more complex or resource-heavy tools.

#### 🎯 Why choose Light Hook Deploy?

[](#-why-choose-light-hook-deploy)

- Effortless setup with no complex configurations or multiple dependencies.
- Seamless integration with version control systems for smooth deployments.
- Lightweight and avoids overloading your environment with unnecessary tools.

📋 Table of Contents
-------------------

[](#-table-of-contents)

- [Description](#description)
- [Features](#features)
- [Getting Started](#getting-started)
- [Deployment Methods](#deployment-methods)
- [CLI Reference](#cli-reference)
- [Next Steps](#next-steps)
- [CLI Scripts Overview](#cli-scripts-overview)
- [Credits](#credits)

Description
-----------

[](#description)

**Light Hook Deploy** enables **automated deployments** via webhooks from services like **GitHub**, **GitLab**, and **Bitbucket**. By leveraging a webhook-based strategy, this microservice seamlessly integrates with your repositories and **triggers deployment scripts** when specific events occur, such as pushing changes to a particular branch.

Unlike **Jenkins** or **Azure Pipelines**, which often require more elaborate configurations and several dependencies, **Light Hook Deploy** is designed to be:

- 🛠️ **Lightweight** and **easy to use**.
- 🚀 Set up your projects and deployment scripts in just a **few steps**.
- 💡 Ideal for environments that don’t need a larger CI/CD ecosystem.

Features
--------

[](#features)

- ⚡ Easy Setup - Quickly configure deployments without complex configurations.
- 🔗 Seamless integration with GitHub, GitLab, and Bitbucket repositories.
- 🚀 Designed for small and medium-sized projects that need reliable automation.
- 💡 Optimized for lean environments - Perfect for servers that don't support heavier tools.
- 🌐 Minimal dependencies - Keeps your system clean and easy to maintain.

Getting Started
---------------

[](#getting-started)

### 📋 Prerequisites

[](#-prerequisites)

Before you begin, make sure your server is set up with the following:

- **PHP 8.2** or **higher**.
- **Composer**: Ensure that Composer is installed for managing PHP dependencies.
- **SSH access** to run deployment scripts.
- A **Git server** or an account on **GitHub**, **GitLab**, or **Bitbucket**.
- `shell_exec` **enabled**: The program uses `shell_exec` to execute scripts, so your PHP configuration must have this function enabled. Ensure that `shell_exec` is not disabled in the `php.ini` file.

### ⚙️ Installation

[](#️-installation)

To install Light Hook Deploy, run the following command using Composer:

```
composer create-project pipestream/light-hook-deploy
```

Next, copy the .env.example file to .env to set up your environment configuration:

```
cp .env.example .env
```

The `.env` file contains the following configuration settings:

```
# Display Slim Errors
DISPLAY_ERROR_DETAILS=true
LOG_ERRORS=true
LOG_ERROR_DETAILS=true

# -------- Request attempts per IP --------
# Redis Configuration for Rate Limiting
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# Rate Limit Configuration (to manage request attempts and prevent brute force attacks)
ENABLE_RATE_LIMIT=false # Enable it if you have Redis configured
MAX_ATTEMPTS_PER_DEPLOY=100
RATE_LIMIT_DEPLOY_MINUTES=60
# -----------------------------------------

# Max execution time
MAX_EXECUTION_TIME=600
```

**Important Note**: The **`MAX_EXECUTION_TIME`** variable is crucial for ensuring sufficient execution time for scripts to avoid `502 Gateway Timeout` errors. It is recommended to extend the timeout settings in `Apache` or `Nginx` (or both, if using Nginx as a reverse proxy).

Additionally, there is Redis configuration available to **block IPs** that attempt to execute deployments through trial and error (**brute force**). To enable Redis for rate limiting, set the following variables in your .env file:

```
ENABLE_RATE_LIMIT=true # Enable it if you have Redis configured
MAX_ATTEMPTS_PER_DEPLOY=100 # Maximum deploy attempts allowed per hour
RATE_LIMIT_DEPLOY_MINUTES=60 # Time frame in minutes for rate limiting
```

In this configuration, you can have a maximum of 100 deployment attempts per hour.

Once the environment is set up, you need to set the permissions for the cli folder to 755 to allow the use of the command-line system:

```
chmod 755 cli
```

Once installed, navigate to the `cli` folder and run the `./lhd-install.sh` script, passing the username as a parameter. This user will be used to execute the deployment scripts from the `./deployments/scripts/` directory.

```
cd cli
./lhd-install.sh
```

#### 👤 User Configuration

[](#-user-configuration)

The `lhd-install.sh` script expects a `` to be passed when running. You can use an existing user, or if needed, the script will guide you through creating a new one. The selected user will be configured to have the necessary permissions for executing the deployment scripts.

- You can assign a user like `www-data` (commonly used by web services), or select a different user to keep deployment tasks independent.
- The script will grant the selected user the following permissions:

    - **Web Service Execution**: The user will have `www-data` privileges for running the service via the web.
    - **Sudo Execution**: Sudo permissions will be restricted to the scripts located in the `scripts` folder within the `deployments` directory.
- The user will be configured in `/etc/passwd` to allow Bash execution, as this is necessary to run deployment scripts. This ensures that the user has the appropriate shell access to execute commands during the deployment process.

#### 🌐 Web Server Configuration

[](#-web-server-configuration)

Make sure your web server (Apache or Nginx) is configured to point to the public directory, where the index.php file is located. This is necessary for the proper functioning of the application.

```
DocumentRoot /path-to-your-project/public
```

Ensure that your Apache or Nginx configuration file is updated to serve content from this directory.

Deployment Methods
------------------

[](#deployment-methods)

1. **Webhook-based Deployment** ⚡

This method utilizes webhooks from services like GitHub, GitLab, or Bitbucket. The service can be configured to listen for any event specified in the webhook section of your repository, such as:

- 🚀 Pushes
- 🔀 Merges
- 📩 Pull requests
- ⚙️ Any other custom event you configure.

When these events are triggered, **Light Hook Deploy** executes the deployment scripts that have been configured for the project.

🔒 You can secure the webhook with a token to ensure that only authenticated requests trigger deployments.

[📚 Read more about Webhook-based Deployment](./Docs/webhook-based-deployments.md)

2. **Manual Deployment via Endpoint** 🔐

Alternatively, you can deploy your project by sending a request to a specific deployment endpoint. This method requires you to provide the **project name** and a **password** to authorize the deployment.

This approach is particularly recommended when continuous integration is handled by the same repository or across different servers and tools, and it’s necessary to connect directly with the project for deployment. For example, if you're using:

- 🔧 Bitbucket Pipelines
- ⚙️ GitHub Actions
- 🔄 GitLab CI/CD

or if you have another server configured for continuous integration, this method ensures that the deployment can be handled on the specific host where the project resides.

✅ This option is ideal when your CI/CD setup needs to interact directly with the deployment host, providing more control over when and how deployments are triggered.

[📚 Read more about Manual Deployment via Endpoint](./Docs/webhook-deployment-via-endpoint.md)

Next Steps
----------

[](#next-steps)

📜 To configure your deployments and scripts effectively, proceed with the following documentation:

- [Configure Deployments and Scripts](./Docs/configuring-deployment-scripts.md): This section will guide you through setting up your webhooks, defining deployment scripts, and ensuring that your integration works smoothly with your version control system. It is essential for making the most out of Light Hook Deploy and ensuring seamless automated deployments.
- [Response Handling and Status Codes](./Docs/api-responses-and-status-codes.md.md): Here, you will learn about how to handle responses and understand the various status codes returned by the deployment endpoints. This knowledge is crucial for troubleshooting and optimizing your deployment processes.

By following these steps, you’ll ensure a robust setup for automated deployments and a clear understanding of how to manage your deployment lifecycle effectively.

CLI Scripts Overview
--------------------

[](#cli-scripts-overview)

📜 To better understand the functionality of the `CLI` scripts within the cli directory, please refer to the following documentation:

- [CLI Scripts Overview](./Docs/command-line-interface.md): This section covers the purpose and functionality of the CLI scripts, such as `lhd-add-deployment-structure.sh`, `lhd-add-secret-token.sh`, and more. These scripts help in configuring deployments, managing access keys, and handling deployment structures effectively. By familiarizing yourself with these scripts, you will be able to manage your deployments efficiently through the command line.

👥 Credits
---------

[](#-credits)

Special thanks to the following contributors for their work on this project:

[![Crisian Martinez Blanco](https://avatars.githubusercontent.com/u/44187907?v=4&s=100)](https://github.com/Cristian-Blanco)[![Gabriel Parra](https://avatars.githubusercontent.com/u/65502363?v=4&s=100)](https://github.com/Gparrac)**[Cristian-Blanco](https://github.com/Cristian-Blanco)****[Gparrac](https://github.com/Gparrac)**

###  Health Score

32

—

LowBetter than 74% of packages

Maintenance38

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 88.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~10 days

Total

6

Last Release

542d ago

Major Versions

1.0.3-beta → 2.0.02024-09-02

### Community

Maintainers

![](https://www.gravatar.com/avatar/ea83929d5c10b7327de7b868724851b44f39933df46ce00e87f3495f280ea472?d=identicon)[Cristian-Blanco](/maintainers/Cristian-Blanco)

---

Top Contributors

[![Cristian-Blanco](https://avatars.githubusercontent.com/u/44187907?v=4)](https://github.com/Cristian-Blanco "Cristian-Blanco (16 commits)")[![Gparrac](https://avatars.githubusercontent.com/u/65502363?v=4)](https://github.com/Gparrac "Gparrac (2 commits)")

### Embed Badge

![Health badge](/badges/pipestream-light-hook-deploy/health.svg)

```
[![Health](https://phpackages.com/badges/pipestream-light-hook-deploy/health.svg)](https://phpackages.com/packages/pipestream-light-hook-deploy)
```

###  Alternatives

[bacula-web/bacula-web

The open source web based reporting and monitoring tool for Bacula

1537.5k](/packages/bacula-web-bacula-web)[lucatacconi/crunz-ui

User interface for lavary/crunz. Integrate Crunz library and funtions: Tabular, monthly or weekly interface to view the scheduled and executed tasks. Quick display of the execution result of the tasks that have been executed (Indicator icons easily show the result). Upload, download, edit or delete tasks. Forced run of the task, even outside the scheduled time with eventual display of the log once the execution is completed. It can be used with integrated Crunz or with a version of Crunz already installed on the system

141.5k](/packages/lucatacconi-crunz-ui)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
