# Configuration

JoobQ provides various configuration options to tailor its behavior to your specific application needs. In this section, we will guide you through how to customize JoobQ, connect it to Redis, and configure job options.

The `JoobQ.configure` block allows you to:

1. **Centralize Configuration**: Define all your queues, schedules, and global settings in one place.
2. **Optimize Performance**: Set worker counts, job retries, and throttling to match your application's requirements.
3. **Enhance Flexibility**: Schedule jobs using cron patterns or time intervals, and integrate custom middlewares to extend functionality.
4. **Improve Reliability**: Enable retries, dead-letter queues, and expiration settings to ensure jobs are processed and errors are handled gracefully.
5. **Monitor and Control**: Enable optional features like REST APIs and statistics tracking for better system visibility.

### Key Features of JoobQ Configuration

* **Queue Management**: Define multiple queues with specific worker counts and job types.
* **Job Scheduling**: Schedule tasks with precision using cron expressions or periodic intervals.
* **Global Customization**: Set defaults for retries, timeouts, and job expiration.
* **Extensibility**: Add custom middlewares for advanced use cases.
* **Resilience**: Leverage throttling, retries, and dead-letter queues for fault tolerance.

### Configuration Guide

This guide provides an overview of configuring **JoobQ**, a job queue system designed for the Crystal programming language. You will learn how to define queues, set up middlewares, schedule jobs, and customize various options to suit your needs.

***

#### Define Configuration

Use the `JoobQ.configure` block to set up your job queue system. This is where you define queues, schedule jobs, and set global options.

```crystal
JoobQ.configure do |config|
  # Enable REST API for monitoring and management
  config.rest_api_enabled = true

  # Define queues with their properties
  queue name: "queue:test", workers: 2, job: TestJob, throttle: nil
  queue name: "queue:fail", workers: 1, job: FailJob
  queue name: "queue:expire", workers: 1, job: ExpireJob

  # Define job schedulers
  scheduler do
    cron(pattern: "*/5 * * * * *") { puts "Every 5 seconds: #{Time.local}" }
    every(1.minute, TestJob, x: 1)
  end
end
```

***

### Key Features and Configuration Options

### 1. **Queues**

Define queues to manage jobs. Each queue can be customized with:

* A **name**.
* The **number of workers**.
* The **job class** to process the tasks.
* Optional **throttling** limits.

#### **Example:**

```crystal
queue name: "queue:my_queue", workers: 5, job: MyJob, throttle: { limit: 10, period: 1.minute }
```

#### **Parameters:**

* `name` - A unique string identifying the queue.
* `workers` - Number of worker threads to handle jobs in the queue.
* `job` - The job class responsible for processing tasks.
* `throttle` (optional) - Limits the number of tasks processed per period.

***

### 2. **Scheduling Jobs**

Jobs can be scheduled using either **cron expressions** or time intervals.

**Using `cron`:**

```crystal
scheduler do
  cron(pattern: "*/5 * * * * *") { puts "Runs every 5 seconds" }
end
```

#### **Using `every`:**

```crystal
scheduler do
  every(10.seconds, MyJob, some_param: "value")
end
```

***

### 3. **Global Settings**

JoobQ provides several global configuration options:

<table><thead><tr><th width="221">Option</th><th width="179">Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>time_location</code></td><td><code>Time::Location.load("America/New_York")</code></td><td>Globally sets the default timezone for JoobQ</td></tr><tr><td><code>rest_api_enabled</code></td><td><code>false</code></td><td>Enables REST API for queue management.</td></tr><tr><td><code>stats_enabled</code></td><td><code>true</code></td><td>Enables gathering of queue statistics.</td></tr><tr><td><code>default_queue</code></td><td><code>"default"</code></td><td>Name of the default queue.</td></tr><tr><td><code>retries</code></td><td><code>3</code></td><td>Number of retries for failed jobs.</td></tr><tr><td><code>expires</code></td><td><code>3.days</code></td><td>Time before a queued job expires.</td></tr><tr><td><code>timeout</code></td><td><code>2.seconds</code></td><td>Timeout for job execution.</td></tr><tr><td><code>failed_ttl</code></td><td><code>3.milliseconds</code></td><td>Time to retain failed job logs.</td></tr><tr><td><code>dead_letter_ttl</code></td><td><code>7.days</code></td><td>Time to retain dead-letter jobs.</td></tr></tbody></table>

#### **Example:**

```crystal
JoobQ.configure do |config|
  config.rest_api_enabled = true
  config.default_queue = "high_priority"
  config.retries = 5
end
```

***

### 4. **Middlewares**

JoobQ supports middlewares to modify job execution behavior. Middlewares are applied in the following order:

1. **Throttle** - Limits job execution rate.
2. **Retry** - Handles job retries on failure.
3. **Timeout** - Enforces execution time limits.

#### **Adding Custom Middleware:**

```crystal
JoobQ.configure do |config|
  config.use do |middlewares|
    middlewares << MyCustomMiddleware.new
  end
end
```

***

### 5. **Time Location**

You can set the global time location for scheduling jobs. By default, it uses `"America/New_York"`.

#### **Example:**

```crystal
JoobQ.configure do |config|
  config.time_location = Time::Location.load("America/New_York")
end
```

***

### Example: Full Configuration

Below is a complete example of a JoobQ configuration:

```crystal
JoobQ.configure do |config|
  config.rest_api_enabled = true
  config.stats_enabled = true
  config.default_queue = "default"
  config.retries = 3
  config.time_location = Time::Location.load("America/New_York")

  # Define queues
  queue name: "queue:email", workers: 3, job: EmailJob, throttle: { limit: 20, period: 1.minute }
  queue name: "queue:report", workers: 2, job: ReportJob

  # Define schedulers
  scheduler do
    cron(pattern: "0 * * * * *") { puts "Hourly task: #{Time.local}" }
    every(1.day, CleanupJob)
  end
end
```

***

### Conclusion

Configuring JoobQ properly allows you to fine-tune its performance, reliability, and responsiveness according to your application’s needs. Now that you understand configuration, let’s dive into some Advanced Features that JoobQ has to offer!