Debian Packaging for easy deploy and update

[Vitexus]

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Create Debian packaging infrastructure for the ISPConfig Zabbix Monitoring project to enable easy installation, removal, and updates through standard Debian package management tools (apt/dpkg).

Observations

Codebase Summary

The ISPConfig Zabbix Monitoring project is a PHP-based monitoring ecosystem that integrates ISPConfig server management with Zabbix 7.4. The project currently uses a manual installation approach via scripts/install.sh that installs files to /usr/local/lib/ispconfig-zabbix-monitoring, configures Zabbix UserParameters, and manages dependencies through Composer. The main components include autodiscovery scripts (src/autodiscovery/), monitoring key readers (src/keys/), core library classes (src/lib/), configuration files (config/), and Zabbix templates (templates/). The project requires PHP 7.4+ with SOAP, JSON, mbstring, and curl extensions, along with Zabbix Agent 2.

Assumptions

Assumption 1: Handling of Composer Dependencies

Options Considered:

• Require Composer on target systems and run composer install during package installation (postinst)
• Bundle pre-installed vendor/ directory within the .deb package
• Package each PHP dependency separately as individual Debian packages following Debian PHP team conventions

Chosen Option: Bundle pre-installed vendor/ directory within the .deb package

Rationale: This approach eliminates the need for Composer on end-user systems, simplifies installation, reduces installation dependencies, and aligns with the existing install.sh behavior which copies vendor/ to the installation directory. This provides the best developer and user experience for a standalone monitoring tool that isn't intended for inclusion in the main Debian repository.

Assumption 2: Configuration File Management Strategy

Options Considered:

• Install config.example.php only and require manual copying to config.php
• Use dpkg conffiles mechanism to manage config.php directly
• Combine both: install config.example.php as reference and create config.php with prompts in postinst if it doesn't exist

Chosen Option: Install config.example.php as documentation and handle config.php creation in postinst with interactive prompts

Rationale: This approach respects Debian conventions where configuration happens after installation, allows users to provide ISPConfig credentials during installation (or skip for later configuration), protects existing configurations during upgrades, and provides a better user experience than manual file copying.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Version Management and Metadata

Establish version control mechanisms to support package versioning and updates.

Task 1: Add VERSION file

Create a VERSION file in the project root to maintain semantic versioning for the package.

• Create VERSION file in project root containing the initial version (e.g., "1.0.0")
• Follow semantic versioning format (MAJOR.MINOR.PATCH)

Task 2: Update composer.json with version

Integrate version management into the existing Composer configuration.

• Update composer.json to read version from VERSION file or set explicit version string
• This ensures consistency between package version and Composer metadata

🤖 Prompt for AI agents

This phase establishes version management for the Debian package.

Create VERSION file:
- Add VERSION file to project root with initial version "1.0.0"
- Use semantic versioning format

Update composer.json:
- Add or update version field to reference VERSION file or set explicit version
- Ensure version consistency between package and Composer metadata

Phase 2: Debian Package Structure

Create the complete debian/ directory structure with all required packaging files following Debian policy and best practices.

Task 1: Create debian/control file

Define package metadata, dependencies, and description.

• Create debian/control with package name "ispconfig-zabbix-monitoring"
• Set Architecture to "all" (PHP scripts are architecture-independent)
• Define dependencies: php (>= 7.4), php-soap, php-json, php-mbstring, php-curl, zabbix-agent2 | zabbix-agent
• Include Suggests for ISPConfig and documentation
• Write comprehensive package description explaining purpose and features

Task 2: Create debian/rules file

Define the build process using debhelper.

• Create debian/rules using dh sequencer for standard build automation
• Add override for dh_auto_build to run composer install --no-dev --optimize-autoloader during build
• Ensure vendor/ directory is included in build output
• Configure dh_auto_clean to remove vendor/ and other build artifacts

Task 3: Create debian/install file

Specify which files and directories to include in the package.

• Create debian/install mapping source files to installation paths
• Map src/ to /usr/local/lib/ispconfig-zabbix-monitoring/src/
• Map vendor/ to /usr/local/lib/ispconfig-zabbix-monitoring/vendor/
• Map config/config.example.php to /usr/local/lib/ispconfig-zabbix-monitoring/config/
• Map templates/ to /usr/share/doc/ispconfig-zabbix-monitoring/templates/

Task 4: Create debian/changelog

Initialize package changelog following Debian conventions.

• Create debian/changelog with initial entry for version 1.0.0
• Follow Debian changelog format (dch tool can help generate this)
• Document initial package release

Task 5: Create debian/compat and debian/source/format

Set debhelper compatibility level and source format.

• Create debian/compat with value "13" (or latest stable debhelper version)
• Create debian/source/format with "3.0 (native)" format for initial implementation

Task 6: Create debian/copyright

Document licensing and copyright information.

• Create debian/copyright in machine-readable format
• Include project license and copyright holders
• Document licenses for bundled Composer dependencies

🤖 Prompt for AI agents

This phase creates the debian/ directory structure with all required packaging
files.

Create debian/control:
- Package name: "ispconfig-zabbix-monitoring"
- Architecture: "all"
- Dependencies: php (>= 7.4), php-soap, php-json, php-mbstring, php-curl,
zabbix-agent2 | zabbix-agent
- Add comprehensive description

Create debian/rules:
- Use dh sequencer
- Override dh_auto_build to run composer install --no-dev --optimize-autoloader
- Override dh_auto_clean to remove vendor/ and build artifacts

Create debian/install:
- Map src/ to /usr/local/lib/ispconfig-zabbix-monitoring/src/
- Map vendor/ to /usr/local/lib/ispconfig-zabbix-monitoring/vendor/
- Map config/config.example.php to
/usr/local/lib/ispconfig-zabbix-monitoring/config/
- Map templates/ to /usr/share/doc/ispconfig-zabbix-monitoring/templates/

Create debian/changelog:
- Initial version 1.0.0 entry in Debian changelog format

Create debian/compat:
- Set debhelper compatibility level to 13

Create debian/source/format:
- Set to "3.0 (native)"

Create debian/copyright:
- Use machine-readable format
- Include project license and bundled dependency licenses

Phase 3: Maintainer Scripts

Implement package installation, upgrade, and removal logic through Debian maintainer scripts.

Task 1: Create debian/postinst script

Handle post-installation configuration and setup.

• Create debian/postinst that executes on "configure" action
• Create /var/log/ispconfig-zabbix-monitoring directory with appropriate permissions (zabbix:zabbix)
• Check if /etc/zabbix/zabbix_agent2.d/ directory exists; if not, fallback to /etc/zabbix/zabbix_agentd.conf.d/ or display warning
• Install Zabbix UserParameter configuration file to /etc/zabbix/zabbix_agent2.d/ispconfig.conf with proper parameter definitions for autodiscovery and monitoring keys
• If config/config.php doesn't exist, optionally prompt user for ISPConfig API credentials using debconf or provide instructions to manually configure
• Use deb-systemd-invoke to restart Zabbix Agent service if it's currently running
• Set proper file ownership (zabbix:zabbix) for installation directory
• Make scripts executable: autodiscovery and keys PHP scripts

Task 2: Create debian/prerm script

Handle pre-removal tasks.

• Create debian/prerm that executes on "remove" or "purge" actions
• On package removal, display message about Zabbix Agent restart requirement
• Do not remove configuration files (handled by postrm during purge)

Task 3: Create debian/postrm script

Handle post-removal cleanup.

• Create debian/postrm that executes on "purge" action
• Remove /var/log/ispconfig-zabbix-monitoring directory on purge
• Remove Zabbix UserParameter configuration file /etc/zabbix/zabbix_agent2.d/ispconfig.conf on purge
• Remove /usr/local/lib/ispconfig-zabbix-monitoring/config/config.php on purge (preserving example file is handled by dpkg)
• Restart Zabbix Agent service after configuration removal using deb-systemd-invoke

Task 4: Create debian/conffiles

Mark configuration files for dpkg protection.

• Create debian/conffiles listing configuration files that should be preserved during upgrades
• Include /usr/local/lib/ispconfig-zabbix-monitoring/config/config.php (if created)
• Include /etc/zabbix/zabbix_agent2.d/ispconfig.conf

🤖 Prompt for AI agents

This phase implements Debian maintainer scripts for installation, upgrade, and
removal.

Create debian/postinst:
- Execute on "configure" action
- Create /var/log/ispconfig-zabbix-monitoring with zabbix:zabbix ownership
- Detect Zabbix agent configuration directory (check
/etc/zabbix/zabbix_agent2.d/ first, fallback to
/etc/zabbix/zabbix_agentd.conf.d/)
- Install ispconfig.conf UserParameter file to detected directory
- Handle config.php creation if it doesn't exist (prompt or provide
instructions)
- Set zabbix:zabbix ownership on installation directory
- Make autodiscovery and keys scripts executable
- Restart Zabbix Agent using deb-systemd-invoke

Create debian/prerm:
- Execute on "remove" or "purge" actions
- Display message about Zabbix Agent restart requirement

Create debian/postrm:
- Execute on "purge" action
- Remove /var/log/ispconfig-zabbix-monitoring
- Remove /etc/zabbix/zabbix_agent2.d/ispconfig.conf
- Remove config.php
- Restart Zabbix Agent using deb-systemd-invoke

Create debian/conffiles:
- List configuration files for dpkg protection
- Include config.php and ispconfig.conf

Phase 4: Zabbix Integration Configuration

Create the Zabbix UserParameter configuration that will be installed by the package.

Create Zabbix UserParameter configuration template

Extract Zabbix configuration from install.sh into a separate file for package installation.

• Create debian/ispconfig.conf.template containing UserParameter definitions
• Define ispconfig.websites.discovery parameter pointing to /usr/local/lib/ispconfig-zabbix-monitoring/src/autodiscovery/websites.php
• Define ispconfig.websites[*] parameter pointing to /usr/local/lib/ispconfig-zabbix-monitoring/src/keys/websites.php with appropriate arguments
• Use absolute paths to PHP binary and scripts
• Ensure parameters match those currently defined in scripts/install.sh

🤖 Prompt for AI agents

This phase creates the Zabbix UserParameter configuration template.

Create debian/ispconfig.conf.template:
- Extract UserParameter definitions from scripts/install.sh
- Define ispconfig.websites.discovery parameter pointing to
/usr/local/lib/ispconfig-zabbix-monitoring/src/autodiscovery/websites.php
- Define ispconfig.websites[*] parameter pointing to
/usr/local/lib/ispconfig-zabbix-monitoring/src/keys/websites.php
- Use absolute paths for PHP binary and scripts
- Match existing parameters from install.sh

Phase 5: Build Process and Documentation

Create build automation and update documentation for package-based installation.

Task 1: Create package build script

Provide convenient script for building the .deb package.

• Create scripts/build-deb.sh in the scripts/ directory
• Script should verify build-dependencies (debhelper, dpkg-dev, composer)
• Run composer install --no-dev to prepare vendor/ directory
• Execute dpkg-buildpackage -us -uc or debuild to build package
• Output .deb file location and basic installation instructions

Task 2: Update README.md

Document the new Debian package installation method.

• Add new "Installation via Debian Package" section to README.md
• Document how to download/build the .deb package
• Provide installation command: sudo dpkg -i ispconfig-zabbix-monitoring_*.deb
• Document dependency installation: sudo apt-get install -f if dependencies are missing
• Explain configuration file location and setup process
• Document upgrade process: installing new .deb over existing installation
• Document removal and purge commands
• Keep existing manual installation instructions as alternative method

Task 3: Create BUILDING.md documentation

Provide comprehensive build instructions for package maintainers.

• Create BUILDING.md in project root documenting the build process
• Explain required build-time tools and dependencies
• Document the debian/ directory structure and purpose of each file
• Provide step-by-step build instructions
• Explain versioning strategy and how to create new releases
• Document testing procedures for built packages (installation, upgrade, removal)

Task 4: Update PROJECT_PLAN.md

Update project plan to reflect packaging implementation.

• Update Phase 5 (Deployment & Maintenance) in PROJECT_PLAN.md to mark Debian packaging as completed
• Document that automated installation process now includes .deb package option
• Keep install.sh as alternative installation method for users who prefer it or need customization

🤖 Prompt for AI agents

This phase creates build automation and updates documentation.

Create scripts/build-deb.sh:
- Verify build dependencies (debhelper, dpkg-dev, composer)
- Run composer install --no-dev
- Execute dpkg-buildpackage -us -uc
- Display .deb location and installation instructions

Update README.md:
- Add "Installation via Debian Package" section
- Document package download/build process
- Provide installation command: sudo dpkg -i ispconfig-zabbix-monitoring_*.deb
- Document dependency resolution: sudo apt-get install -f
- Explain configuration location and setup
- Document upgrade, removal, and purge processes
- Preserve existing manual installation instructions

Create BUILDING.md:
- Document build requirements and dependencies
- Explain debian/ directory structure
- Provide step-by-step build instructions
- Document versioning strategy for new releases
- Include package testing procedures

Update PROJECT_PLAN.md:
- Mark Debian packaging as completed in Phase 5
- Document .deb package as new installation option
- Keep install.sh as alternative method

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase establishes version management for the Debian package.

Create VERSION file:
- Add VERSION file to project root with initial version "1.0.0"
- Use semantic versioning format

Update composer.json:
- Add or update version field to reference VERSION file or set explicit version
- Ensure version consistency between package and Composer metadata
===============================================================================

Task: 2

This phase creates the debian/ directory structure with all required packaging
files.

Create debian/control:
- Package name: "ispconfig-zabbix-monitoring"
- Architecture: "all"
- Dependencies: php (>= 7.4), php-soap, php-json, php-mbstring, php-curl,
zabbix-agent2 | zabbix-agent
- Add comprehensive description

Create debian/rules:
- Use dh sequencer
- Override dh_auto_build to run composer install --no-dev --optimize-autoloader
- Override dh_auto_clean to remove vendor/ and build artifacts

Create debian/install:
- Map src/ to /usr/local/lib/ispconfig-zabbix-monitoring/src/
- Map vendor/ to /usr/local/lib/ispconfig-zabbix-monitoring/vendor/
- Map config/config.example.php to
/usr/local/lib/ispconfig-zabbix-monitoring/config/
- Map templates/ to /usr/share/doc/ispconfig-zabbix-monitoring/templates/

Create debian/changelog:
- Initial version 1.0.0 entry in Debian changelog format

Create debian/compat:
- Set debhelper compatibility level to 13

Create debian/source/format:
- Set to "3.0 (native)"

Create debian/copyright:
- Use machine-readable format
- Include project license and bundled dependency licenses
===============================================================================

Task: 3

This phase implements Debian maintainer scripts for installation, upgrade, and
removal.

Create debian/postinst:
- Execute on "configure" action
- Create /var/log/ispconfig-zabbix-monitoring with zabbix:zabbix ownership
- Detect Zabbix agent configuration directory (check
/etc/zabbix/zabbix_agent2.d/ first, fallback to
/etc/zabbix/zabbix_agentd.conf.d/)
- Install ispconfig.conf UserParameter file to detected directory
- Handle config.php creation if it doesn't exist (prompt or provide
instructions)
- Set zabbix:zabbix ownership on installation directory
- Make autodiscovery and keys scripts executable
- Restart Zabbix Agent using deb-systemd-invoke

Create debian/prerm:
- Execute on "remove" or "purge" actions
- Display message about Zabbix Agent restart requirement

Create debian/postrm:
- Execute on "purge" action
- Remove /var/log/ispconfig-zabbix-monitoring
- Remove /etc/zabbix/zabbix_agent2.d/ispconfig.conf
- Remove config.php
- Restart Zabbix Agent using deb-systemd-invoke

Create debian/conffiles:
- List configuration files for dpkg protection
- Include config.php and ispconfig.conf
===============================================================================

Task: 4

This phase creates the Zabbix UserParameter configuration template.

Create debian/ispconfig.conf.template:
- Extract UserParameter definitions from scripts/install.sh
- Define ispconfig.websites.discovery parameter pointing to
/usr/local/lib/ispconfig-zabbix-monitoring/src/autodiscovery/websites.php
- Define ispconfig.websites[*] parameter pointing to
/usr/local/lib/ispconfig-zabbix-monitoring/src/keys/websites.php
- Use absolute paths for PHP binary and scripts
- Match existing parameters from install.sh
===============================================================================

Task: 5

This phase creates build automation and updates documentation.

Create scripts/build-deb.sh:
- Verify build dependencies (debhelper, dpkg-dev, composer)
- Run composer install --no-dev
- Execute dpkg-buildpackage -us -uc
- Display .deb location and installation instructions

Update README.md:
- Add "Installation via Debian Package" section
- Document package download/build process
- Provide installation command: sudo dpkg -i ispconfig-zabbix-monitoring_*.deb
- Document dependency resolution: sudo apt-get install -f
- Explain configuration location and setup
- Document upgrade, removal, and purge processes
- Preserve existing manual installation instructions

Create BUILDING.md:
- Document build requirements and dependencies
- Explain debian/ directory structure
- Provide step-by-step build instructions
- Document versioning strategy for new releases
- Include package testing procedures

Update PROJECT_PLAN.md:
- Mark Debian packaging as completed in Phase 5
- Document .deb package as new installation option
- Keep install.sh as alternative method

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!