# Redmine Scheduler Plugin

A lightweight scheduling trigger plugin for **Redmine 7.0.0+**. 

Rather than embedding heavy task execution logic directly into this plugin, `redmine_scheduler` acts as a central execution coordinator. On a configured schedule (hourly, daily, etc.), it triggers custom Redmine hooks that your other plugins can listen to and execute business logic (such as sending SMS appointment reminders, processing cleanups, or synchronizing external data).

---

## Features

* **Decoupled Architecture:** Coordinates schedules via Redmine's built-in `Redmine::Hook` mechanism.
* **Zero Overhead:** Keeps background processes out of the core Rails web application.
* **Docker Ready:** Seamlessly integrates with system `cron` or container schedulers like **Ofelia**.
* **Extensible:** Easily add new schedule intervals or custom domain-specific hook triggers.

---

## Prerequisites

* **Redmine:** `5.0.0` or higher (Fully tested on `7.0.0`)
* **Ruby:** `3.2+`
* **Scheduler runner:** System `cron`, Docker `exec`, or a sidecar scheduler container (e.g., [Ofelia](https://github.com/mcuadros/ofelia)).

---

## Installation

1. Clone or copy the plugin repository into your Redmine `plugins` directory:

   ```bash
   cd /path/to/redmine/plugins
   git clone https://github.com/your-org/redmine_scheduler.git
   ```

2. Restart your Redmine application instance:

   * **Standard deployment:** Restart Puma/Unicorn or `touch tmp/restart.txt`.
   * **Docker deployment:** `docker compose restart redmine`

---

## Directory Structure

```text
plugins/redmine_scheduler/
├── init.rb
├── README.md
├── lib/
│   ├── redmine_scheduler/
│   │   └── runner.rb
│   └── tasks/
│       └── scheduler.rake
```

---

## Available Schedules & Hooks

The plugin exposes the following custom Redmine hooks:

| Hook Symbol | Trigger Frequency | Typical Use Case |
| :--- | :--- | :--- |
| `:redmine_scheduler_hourly` | Every hour | High-priority syncs, queue processing |
| `:redmine_scheduler_daily` | Once per day | Summary reports, database maintenance |

---

## How to Listen to Hooks in Other Plugins

To consume scheduled events in your other custom plugins register a listener using Redmine's `Redmine::Hook::Listener` base class.

### 1. Create a Listener Class

```ruby
module YourRedminePlugin
  class Hooks < Redmine::Hook::Listener
    # The method name must match the hook symbol defined in the scheduler
    def redmine_scheduler_hourly(context = {})
      # TODO scheduled task
    end
  end
end
```

---

## Execution & Deployment Methods

### Method A: Docker Compose with Ofelia (Recommended)

If you run Redmine inside Docker, you can use **Ofelia** as a sidecar container to trigger tasks without installing `cron` inside the main container.

Add the following to your `docker-compose.yml`:

```yaml
version: '3.8'

services:
  redmine:
    image: redmine:7.0.0
    container_name: redmine_app
    ports:
      - "3000:3000"
    volumes:
      - ./plugins:/usr/src/redmine/plugins

  ofelia:
    image: mcuadros/ofelia:latest
    container_name: redmine_cron
    command: daemon --docker
    depends_on:
      - redmine
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:
      # Hourly job (runs every hour on minute 0)
      ofelia.job-exec.hourly_reminders.schedule: "0 0 * * * *"
      ofelia.job-exec.hourly_reminders.container: "redmine_app"
      ofelia.job-exec.hourly_reminders.command: "bundle exec rake redmine_scheduler:run_hourly RAILS_ENV=production"

      # Daily job (runs every day at 7:00 AM)
      ofelia.job-exec.daily_reminders.schedule: "0 0 7 * * *"
      ofelia.job-exec.daily_reminders.container: "redmine_app"
      ofelia.job-exec.daily_reminders.command: "bundle exec rake redmine_scheduler:run_daily RAILS_ENV=production"
```

Apply changes:

```bash
docker compose up -d ofelia
```

---

### Method B: Host System Crontab (Docker `exec`)

To trigger tasks directly from the host machine's system `cron`:

```bash
# Open host crontab
crontab -e

# Add execution rules:
0 * * * * docker exec -u redmine redmine_app bundle exec rake redmine_scheduler:run_hourly RAILS_ENV=production >> /var/log/redmine_scheduler.log 2>&1
0 7 * * * docker exec -u redmine redmine_app bundle exec rake redmine_scheduler:run_daily RAILS_ENV=production >> /var/log/redmine_scheduler.log 2>&1
```

---

### Method C: Standard Server Crontab (Non-Docker)

If Redmine is hosted directly on a bare-metal or VM instance:

```bash
0 * * * * cd /var/www/redmine && RAILS_ENV=production bundle exec rake redmine_scheduler:run_hourly >> log/scheduler.log 2>&1
0 7 * * * cd /var/www/redmine && RAILS_ENV=production bundle exec rake redmine_scheduler:run_daily >> log/scheduler.log 2>&1
```

---

## Manual Testing

You can trigger tasks manually via shell/terminal to verify hook listeners:

```bash
# Execute hourly hook runner
bundle exec rake redmine_scheduler:run_hourly RAILS_ENV=production

# Execute daily hook runner
bundle exec rake redmine_scheduler:run_daily RAILS_ENV=production
```

Check Redmine's production log (`log/production.log`) to confirm execution:

```bash
tail -f log/production.log | grep "[RedmineScheduler]"
```

---

## License

The MIT License (MIT)

Copyright (c) 2026 Rick Barrette

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.