Installation

Installation

This guide covers installation of the Redmine Webhook Plugin for production Redmine environments.

Table of Contents

• Prerequisites
• Method 1: Automated Installer (Recommended)
• Method 2: Manual Installation
• Installation Verification
• Uninstallation
• Troubleshooting Installation

---

Prerequisites

System Requirements

Requirement	Minimum	Recommended
Redmine	5.1.0	Latest stable
Ruby	3.0	3.2+
Database	SQLite 3+	PostgreSQL 12+ / MySQL 8+
Web Server	Any Redmine-compatible	Nginx + Puma / Apache
Disk Space	100 MB	500 MB+ for logs
Network	HTTPS outbound	Stable internet connection

Required Software

# Check Ruby version
ruby -v

# Check Redmine version
cd /var/www/redmine && cat VERSION

# Check bundler
bundle -v

User Permissions

You need either:

1. Root access for installation, OR
2. Sudo access on Redmine server

Network Requirements

• Outbound HTTPS (port 443) to webhook endpoints
• DNS resolution for webhook domain names
• No proxy blocking outbound connections

---

Method 1: Automated Installer (Recommended)

Download the Plugin

# Download latest release
wget https://github.com/guyinwonder168/redmine_webhook_plugin/archive/refs/tags/v1.0.0-RC1.tar.gz

# Extract
tar -xzf redmine_webhook_plugin-v1.0.0-RC1.tar.gz
cd redmine_webhook_plugin

Run the Installer

# Basic installation
sudo ./installer/install.sh -d /var/www/redmine

# Installation with web server restart
sudo ./installer/install.sh -d /var/www/redmine -R -u www-data

# Installation with backup
sudo ./installer/install.sh -d /var/www/redmine -b /backup/redmine_plugin

Installer Options

Option	Short	Description	Default
--redmine-dir	-d	Redmine installation path	Required
--source	-s	Plugin source or GitHub URL	Current directory
--backup	-b	Backup directory	./backups/timestamp
--skip-backup	-B	Skip backup	false
--skip-migrations	-M	Skip DB migrations	false
--restart-server	-R	Restart web server	false
--web-user	-u	Web server user	(none)
--rails-env	-e	Rails environment	production
--version	-v	Plugin version to install	1.0.0-RC1
--help	-h	Show help	-

Installation Example

# Full production installation
sudo ./installer/install.sh \
  --redmine-dir /var/www/redmine \
  --web-user www-data \
  --restart-server \
  --backup /backups/redmine_plugin_$(date +%Y%m%d)

---

Method 2: Manual Installation

Clone or Extract

# Clone from GitHub
cd /var/www/redmine/plugins
git clone https://github.com/guyinwonder168/redmine_webhook_plugin.git

# OR extract from archive
tar -xzf redmine_webhook_plugin-v1.0.0-RC1.tar.gz -C /var/www/redmine/plugins/

Install Dependencies

cd /var/www/redmine
bundle install

Run Database Migrations

cd /var/www/redmine
RAILS_ENV=production bundle exec rake redmine:plugins:migrate NAME=redmine_webhook_plugin

Restart Web Server

# For Puma/Unicorn
sudo systemctl restart puma

# For Apache + Passenger
sudo systemctl reload apache2

# For Nginx + Puma
sudo systemctl restart nginx
sudo systemctl restart puma

---

Installation Verification

1. Check Plugin Registration

1. Login to Redmine as administrator
2. Navigate to: Administration > Plugins
3. Look for: Redmine Webhook Plugin in the list
4. Verify version: 1.0.0-RC1

2. Verify Database Tables

cd /var/www/redmine
RAILS_ENV=production bundle exec rails db

# Run in Rails console
ActiveRecord::Base.connection.tables

Expected tables:

• webhook_endpoints
• webhook_deliveries

3. Check Web Server Logs

# For Puma
sudo journalctl -u puma -n 50

# For Apache
sudo tail -f /var/log/apache2/error.log

Look for:

• Plugin loaded without errors
• No migration errors
• Database connections successful

---

Uninstallation

Run Uninstaller

cd redmine_webhook_plugin
sudo ./installer/uninstall.sh -d /var/www/redmine -R

Uninstaller Options

Option	Short	Description	Default
--redmine-dir	-d	Redmine installation path	Required
--skip-db-rollback	-B	Skip database rollback	false
--skip-webhook-restore	-W	Skip native webhook re-enable	false
--restart-server	-R	Restart web server	false
--web-user	-u	Web server user	(none)
--rails-env	-e	Rails environment	production

What Gets Removed

Plugin Files:

• /var/www/redmine/plugins/redmine_webhook_plugin/ directory

Database Tables:

• webhook_endpoints table (rolled back)
• webhook_deliveries table (rolled back)

Native Webhooks (Redmine 7+):

• Automatically re-enabled by uninstaller
• Web server restart required

Uninstallation Example

# Complete uninstallation
sudo ./installer/uninstall.sh \
  --redmine-dir /var/www/redmine \
  --restart-server \
  --web-user www-data

---

Troubleshooting Installation

Plugin Not Appearing in Redmine

Symptom: Plugin not listed in Administration > Plugins

Solutions:

1. Check file permissions:

   ls -la /var/www/redmine/plugins/redmine_webhook_plugin
   # Should be owned by web user
   sudo chown -R www-data:www-data /var/www/redmine/plugins/redmine_webhook_plugin

2. Check migrations:

   cd /var/www/redmine
   RAILS_ENV=production bundle exec rake redmine:plugins:migrate NAME=redmine_webhook_plugin

3. Restart web server:

   sudo systemctl restart puma
   # or
   sudo systemctl reload apache2

Migration Failures

Symptom: Migrations fail with errors

Solutions:

1. Check database connection:

   cd /var/www/redmine
   RAILS_ENV=production bundle exec rake db:migrate:status

2. Check for pending migrations:

   cd /var/www/redmine
   RAILS_ENV=production bundle exec rake redmine:plugins:migrate:status

3. Rollback and retry:

   RAILS_ENV=production bundle exec rake redmine:plugins:migrate NAME=redmine_webhook_plugin VERSION=0
   RAILS_ENV=production bundle exec rake redmine:plugins:migrate NAME=redmine_webhook_plugin

Permission Errors

Symptom: Permission denied on directories or files

Solution:

# Set correct ownership
sudo chown -R www-data:www-data /var/www/redmine/plugins/redmine_webhook_plugin

# Set correct permissions
sudo chmod -R 755 /var/www/redmine/plugins/redmine_webhook_plugin

---

Advanced Installation

Install to Multiple Redmine Instances

# Script to install to multiple instances
for redmine_dir in /var/www/redmine-prod /var/www/redmine-staging; do
  ./installer/install.sh -d "$redmine_dir" -R
done

Install from Custom Source Directory

# Install from local development copy
sudo ./installer/install.sh -d /var/www/redmine -s /path/to/dev/plugin

Install Specific Version

# Install specific version from GitHub
sudo ./installer/install.sh \
  -d /var/www/redmine \
  -s https://github.com/guyinwonder168/redmine_webhook_plugin/archive/refs/tags/v1.0.0-RC1.tar.gz \
  -v v1.0.0-RC1

---

Installation Checklist

Before production deployment, ensure:

• Redmine version 5.1.0 or higher installed
• Ruby 3.x available
• Sudo or root access available
• HTTPS outbound connectivity to webhook endpoints
• Backup of Redmine created
• Database backup created (optional but recommended)
• Installation tested in staging environment

---

Need Help? See Home or Troubleshooting