reproq-django

Deployment Guide

Reproq is designed for stability in production environments. Follow these guidelines for a robust setup.

0. Deployment Options

Option A (Recommended): Separate worker + scheduler processes

Option B: Single-service (web + worker + scheduler)

Only one beat instance should run per database.

With SDK 0.1.532 or later, the packaged supervisor can run web-only: set REPROQ_WORKER_ENABLED=false and REPROQ_SCHEDULER_MODE=off. Worker activation defaults to enabled; empty worker commands retain the default command rather than disabling it. See Render deployment for the accepted boolean values, unchanged prestart checks and custom-prestart contract.

Deploy the compatible SDK and worker together. The executor configuration contract defines --python-bin, file and CLI precedence, and the worker_python_bin:1 capability. Prestart and doctor verify that capability. Start the shared Render environment through one uv run invocation so executor launches can reuse its selected Python.

See the CLI reference for full command examples.

Generate service files for Linux servers running systemd 251 or newer. Older systems, including Ubuntu 22.04 and Debian 11, can use manually configured units for the chosen scheduler. Render uses its own supervisor.

uv run python manage.py reproq systemd --concurrency 20

To bake metrics settings into the unit files:

uv run python manage.py reproq systemd --metrics-addr 127.0.0.1:9090 --metrics-allow-cidrs "127.0.0.1/32"

You can also provide an environment file. Give one exact path. A relative path is resolved against the project directory, and the file must exist at service startup.

uv run python manage.py reproq systemd --env-file /etc/reproq-worker.env

The project directory name becomes part of the unit filenames. Use a name containing letters, digits, periods, underscores, colons or hyphens. The generated units include reproq-worker-<project>.service for execution and reproq-beat-<project>.service for periodic scheduling.

The generated beat and schedule conditions skip startup when the configured mode selects another scheduler. A skip does not trigger the beat restart policy. The log records which command was skipped.

Manual Installation

For a project directory named myapp, copy the generated files to /etc/systemd/system/ and enable them.

sudo cp reproq-worker-myapp.service reproq-beat-myapp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now reproq-worker-myapp.service
sudo systemctl enable --now reproq-beat-myapp.service

2. Environment Variables

The Go worker needs access to your database. It respects the following:

The SDK derives its DSN from the selected Django queue alias and verifies namespaced environment/configuration alignment; business DATABASE_URL is preserved for Python tasks.

If you want all Reproq tables to live in a non-default database alias, set REPROQ_DEFAULT_DB_ALIAS and add the router to Django settings:

DATABASE_ROUTERS = ["reproq_django.db_router.ReproqRouter"]

Worker binary resolution order:

  1. REPROQ_WORKER_BIN (setting or env)
  2. ./.reproq/bin/reproq (installed by reproq install)
  3. reproq_django/bin/reproq (packaged fallback)
  4. PATH

Schema Compatibility

Committed ReproQ Django migrations own queue schema DDL. Follow the migration and guarded adoption procedure for fresh queues and existing legacy schemas. Adoption verifies catalog structure and migration history before any explicit reconciliation.

2a. Metrics & Health Hardening

If you enable metrics (via --metrics-port or --metrics-addr), secure the endpoint:

3. Worker Concurrency

The number of concurrent tasks a single worker process can handle is configurable.

uv run python manage.py reproq worker --concurrency 50

Queue selection uses --queues (comma-separated). The retired --queue option is rejected; update existing command lines to --queues. Use --database <alias> when a worker should target a non-default queue database.

4. Periodic Tasks (Beat or pg_cron)

Assign each periodic definition to either Go or pg_cron. A queue database can use both providers for different definitions. For Go-owned definitions, use one supervised beat process or one external timer per database.

Replaying the same (periodic_name, scheduled_for) occurrence reuses its existing run. Before changing a definition’s provider, reconcile the old jobs and the new provider’s schedule. Go and pg_cron derive occurrence times differently. See the periodic task contract.

Option A: Beat

Start beat as a dedicated process (recommended when pg_cron is unavailable):

uv run python manage.py reproq beat --interval 30s

If you cannot run a persistent beat process, choose one external cron entry instead. Use the project’s working directory and the absolute UV executable:

* * * * * cd /path/to/project && /absolute/path/to/uv run python manage.py reproq schedule

You can also generate a systemd timer to run reproq schedule every minute:

uv run python manage.py reproq systemd --schedule --schedule-on-calendar "*-*-* *:*:00"

Enable the timer, and set REPROQ_SCHEDULER_MODE=cron in your EnvironmentFile to ensure only the cron-style scheduler runs:

sudo cp reproq-schedule-<project>.service reproq-schedule-<project>.timer /etc/systemd/system/
sudo systemctl enable --now reproq-schedule-<project>.timer

Option B: pg_cron

Retain this provider when the database can host native scheduling and a separate beat process would be wasteful. A database administrator must install/preload pg_cron in the selected queue database, grant the application’s role access, and configure native job connections/background workers. ReproQ never creates extensions or independently repairs queue DDL. Check the installed extension:

SELECT extversion FROM pg_catalog.pg_extension WHERE extname = 'pg_cron';
SELECT current_setting('cron.timezone', true);

Register definitions through register_periodic(..., scheduler_provider="pg_cron"); see the canonical registration API. The native server zone must match each selected definition’s CRON_TZ (bare expressions mean UTC). Reconcile explicitly after registration:

uv run python manage.py reproq pg-cron --install --dry-run
uv run python manage.py reproq pg-cron --install
# Stops exact known owned jobs, never drops extensions/functions:
uv run python manage.py reproq pg-cron --remove

The adapter validates all selected jobs before writes and fails on an unknown command/name in its namespace. It only changes jobs in the current database owned by the current database role. --if-supported skips an unavailable native capability; invalid definitions/zones still fail. Removal works before schema2 so legacy native jobs can be stopped before forward migration0003 retires their exact known old helper. Stop other schedulers/workers for that migration plan.

Native jobs invoke the shared migration-owned enqueue function; they do not construct JSON or hashes. Native occurrence identity is the UTC execution minute, and missed/queued execution follows pg_cron. It is not Go’s nominal-tick replay or synthetic next-run calculation. Check cron.job_run_details for actual run success, not just extension presence. The worker is still needed to execute Python tasks. Use task.enqueue() for an independent ad-hoc run.

4a. Reclaiming Orphaned Tasks

If a worker dies while holding a lease, tasks can remain stuck in RUNNING. Use the reclaim command to requeue or fail those stale tasks:

uv run python manage.py reproq reclaim --older-than 5m --action requeue

5. Reverse Proxy & Admin

The Reproq Admin uses standard Django Admin templates. Ensure your static files are collected and served correctly:

uv run python manage.py collectstatic

6. Render Deployment Note

When deploying on Render, apply committed Django migrations during pre-deploy:

uv run python manage.py migrate --noinput

For a separate queue database, also run uv run python manage.py reproq migrate-worker --database <alias>. It delegates to the same committed migrations. Existing legacy schemas require guarded adoption after producers/workers are quiescent; ordinary deployment does not perform an automatic repair.

After migrations complete, enqueue any deploy-time tasks (such as deploy notifications or periodic task seeds). Enqueuing before schema setup can fail silently or create partial task records.

If you run worker + beat in the same service as the web process, avoid enqueueing deploy-time tasks in a pre-deploy hook. Older worker processes can still claim the task with outdated environment settings. Prefer a post-start enqueue guarded by a deploy identifier (for example, RENDER_DEPLOY_ID) so the task runs once per deploy.

7. Troubleshooting Runbook

Tasks stuck in RUNNING

Allowlist errors or missing tasks

Schema mismatch or missing columns

DSN or config precedence confusion

No logs available