Configuration - Nuvom
Author: Nahom Zewdu
Description: Lightweight, plugin-first Python task queue — no Redis required.

Skip to content

# Nuvom Configuration Guide

Nuvom is highly configurable using environment variables and `.env` files. This guide explains all supported settings, how they affect runtime behavior, and how to configure plugins.

## 📁 Where Settings Come From

Nuvom loads configuration from:

1. `.env` file in your project root (uses `pydantic-settings`)
2. Environment variables (`export FOO=...`)
3. Defaults defined in code (if no value is provided)

## 🗃 Example `.env`

    NUVOM_ENVIRONMENT=dev
    NUVOM_LOG_LEVEL=INFO
    NUVOM_QUEUE_BACKEND=file
    NUVOM_RESULT_BACKEND=memory
    NUVOM_SERIALIZATION_BACKEND=msgpack
    NUVOM_MAX_WORKERS=4
    NUVOM_BATCH_SIZE=10
    NUVOM_JOB_TIMEOUT_SECS=30
    NUVOM_MANIFEST_PATH=.nuvom/manifest.json
    NUVOM_TIMEOUT_POLICY=retry
    NUVOM_PROMETHEUS_PORT=9150
    NUVOM_SQLITE_QUEUE_PATH=.nuvom/queue.db
    NUVOM_SQLITE_RESULT_PATH=.nuvom/results.db
    ````

    ---

    ## ⚙️ Core Configuration Variables

    | Variable                      | Description                                              | Default                |
    | ----------------------------- | -------------------------------------------------------- | ---------------------- |
    | `NUVOM_ENVIRONMENT`           | `dev`, `test`, or `prod`                                 | `dev`                  |
    | `NUVOM_LOG_LEVEL`             | Logging level: `DEBUG`, `INFO`, etc.                     | `INFO`                 |
    | `NUVOM_QUEUE_BACKEND`         | Backend type: `memory`, `file`, or plugin name           | `memory`               |
    | `NUVOM_RESULT_BACKEND`        | Result store: `memory`, `file`, `sqlite`, or plugin name | `memory`               |
    | `NUVOM_SERIALIZATION_BACKEND` | Format: `msgpack` (others in future)                     | `msgpack`              |
    | `NUVOM_MANIFEST_PATH`         | Task discovery manifest path                             | `.nuvom/manifest.json` |
    | `NUVOM_JOB_TIMEOUT_SECS`      | Default job timeout (if not overridden in `@task`)       | `30`                   |
    | `NUVOM_BATCH_SIZE`            | Jobs pulled at once per worker cycle                     | `10`                   |
    | `NUVOM_MAX_WORKERS`           | Number of worker threads to spawn                        | `4`                    |
    | `NUVOM_TIMEOUT_POLICY`        | Behavior on timeout: `retry`, `fail`, `ignore`           | `retry`                |

    ---

    ## 🧩 Plugin Configuration

    Plugins are registered via `.nuvom_plugins.toml` in the root of your project.

    ```toml
    [plugins]
    queue_backend = ["my_module:MyQueuePlugin"]
    result_backend = ["my_module:MyResultPlugin"]
    monitoring = ["nuvom.plugins.monitoring.prometheus:PrometheusPlugin"]

Use your `.env` to pass any plugin-specific values:

    NUVOM_PROMETHEUS_PORT=9150
    MY_PLUGIN_AUTH_TOKEN=abc123

Inside the plugin, access them via the `settings` argument passed to `start()`:

    def start(self, settings):
        port = settings.get("prometheus_port", 9150)

## 🧠 SQLite Backend Settings

If you use the SQLite queue or result backend, configure paths:

Variable | Purpose | Default
--- | --- | ---
`NUVOM_SQLITE_QUEUE_PATH` | SQLite file path for the job queue | `.nuvom/queue.db`
`NUVOM_SQLITE_RESULT_PATH` | SQLite file path for result backend | `.nuvom/results.db`

Ensure the directories exist or Nuvom will create them automatically.

## 🧪 CLI to View Active Config

You can inspect current config at any time:

    nuvom config

Output:

    Environment: dev
    Queue Backend: file
    Result Backend: sqlite
    Max Workers: 4
    Batch Size: 10
    Manifest Path: .nuvom/manifest.json
    ...

## 🔐 Best Practices

- Commit a `.env.example` file for contributors
- Don’t hardcode secrets or plugin tokens
- Keep `.env` out of version control (`.gitignore`)
- Use `dotenv` or OS environment overrides in CI/CD

## 🧩 Summary

Nuvom gives you full control over how it runs, queues jobs, stores results, and loads plugins — all through a clean `.env` and TOML-based system.

You can:

- Swap backends without changing code
- Override runtime behavior with simple settings
- Pass config to your own plugins
- Use the CLI to verify current values

> Simple configs. Powerful control.

July 16, 2025