> For the complete documentation index, see [llms.txt](https://docs.joobq.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.joobq.io/configuration.md).

# Configuration

Keep queue definitions, environment settings, and deployment secrets separate.

Configure producers and workers from the same initializer. Both must agree on Redis, queue names, job types, and serialized fields. Keep the initializer free of server startup; run `JoobQ.forge` only in the worker entry point.

## Queue defaults

| Setting             | Core baseline default | Meaning                                                                                   |
| ------------------- | --------------------- | ----------------------------------------------------------------------------------------- |
| `default_queue`     | `"default"`           | Default queue name; still register a concrete job type                                    |
| `retries`           | `3`                   | Retry budget after the initial attempt                                                    |
| `expires`           | `3.days`              | Job age limit                                                                             |
| `timeout`           | `2.seconds`           | Configuration value; **not** a universal cancellation deadline for arbitrary handler code |
| `worker_batch_size` | `10`                  | Maximum in-flight claims per legacy worker loop, also limiting each fetch                 |
| `failed_ttl`        | `7.days`              | Configuration value; no failed-record expiry enforcement in these baselines               |
| `dead_letter_ttl`   | `7.days`              | Configuration value; the Redis DLQ writer does not enforce this TTL                       |
| `rest_api_enabled`  | `false`               | Management listener                                                                       |
| `stats_enabled`     | `true`                | Core statistics tracking                                                                  |

The baseline timeout middleware checks expiration before invoking the job. Put deadlines on HTTP, SQL, and other blocking operations inside your handler. Do not rely on `config.timeout` to stop a payment request already in flight.

## Where configuration comes from

Core can discover YAML files in project, configuration, user, and system locations. Environment-specific files are considered first. `JOOBQ_ENV`, `RACK_ENV`, and `CRYSTAL_ENV` participate in that lookup. `JOOBQ_CONFIG_PATH` and `JOOBQ_CONFIG_FILE` are candidates in the discovery list; they do not universally override an earlier matching file.

Explicit initializer configuration is easiest to audit. If you choose YAML loading or environment override helpers, use one deliberate loading path and test its effective values. Avoid having multiple initializers replace the store or queue registry independently.

{% hint style="warning" %}
Never log a complete Redis URL, password, management token, license, or job payload to explain configuration. Log the endpoint host, queue names, enabled features, and connection outcome instead.
{% endhint %}

Continue with [Redis connections](/configuration/redis.md), [concurrency and shutdown](/configuration/concurrency.md), and [management access](/configuration/access.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.joobq.io/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.