Reproq is designed for stability in production environments. Follow these guidelines for a robust setup.
Option A (Recommended): Separate worker + scheduler processes
uv run python manage.py reproq worker and either uv run python manage.py reproq beat or uv run python manage.py reproq pg-cron --install.--database).Option B: Single-service (web + worker + scheduler)
pg_cron and omit beat.reproq_django.resources/render_start.sh supervisor; see
Render deployment. Start with one task slot and measure combined
web/Go/Python peak memory before increasing concurrency.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.
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
The Go worker needs access to your database. It respects the following:
REPROQ_DATABASE_URL: Standard PostgreSQL DSN (e.g., postgres://user:pass@host:5432/dbname). Optional if you provide --dsn or a config file with dsn.WORKER_ID: Unique name for the worker node (defaults to hostname).PYTHONPATH: Ensure your Django project is importable.REPROQ_WORKER_BIN: Optional explicit path to the worker binary. If set, uv run python manage.py reproq install writes the binary to this path.
If unset, the default install target is ./.reproq/bin/reproq.METRICS_TLS_CERT: Optional TLS certificate path for health/metrics.METRICS_TLS_KEY: Optional TLS private key path for health/metrics.METRICS_TLS_CLIENT_CA: Optional client CA bundle to require mTLS for health/metrics.ALLOWED_TASK_MODULES: Optional allow-list for task module prefixes. If unset, uv run python manage.py reproq worker auto-configures it from discovered task modules.REPROQ_LOGS_DIR: Optional directory to persist worker stdout/stderr logs (updates task_runs.logs_uri).REPROQ_QUEUE_DATABASES: Map queue names (or globs) to Django database aliases for multi-DB routing.REPROQ_DEFAULT_DB_ALIAS: Override the default database alias for queues (defaults to default).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:
REPROQ_WORKER_BIN (setting or env)./.reproq/bin/reproq (installed by reproq install)reproq_django/bin/reproq (packaged fallback)PATHCommitted 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.
If you enable metrics (via --metrics-port or --metrics-addr), secure the endpoint:
--metrics-addr 127.0.0.1:9090).METRICS_AUTH_TOKEN to require a bearer token.METRICS_ALLOW_CIDRS to restrict access by IP or CIDR.The number of concurrent tasks a single worker process can handle is configurable.
number of cores.20-50).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.
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.
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
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.
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
The Reproq Admin uses standard Django Admin templates. Ensure your static files are collected and served correctly:
uv run python manage.py collectstatic
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.
Tasks stuck in RUNNING
uv run python manage.py reproq reclaim --older-than 5m --action requeue--action failuv run python manage.py reproq status)Allowlist errors or missing tasks
uv run python manage.py reproq allowlist --write --config reproq.yamlALLOWED_TASK_MODULES=* disables validation.Schema mismatch or missing columns
uv run python manage.py reproq migrate-worker and re-check uv run python manage.py reproq doctor.reproq adopt-schema --inspect and the explicit
audited adoption procedure. Do not apply retired Go SQL migrations or manual
DDL repairs.DSN or config precedence confusion
uv run python manage.py reproq config --explain to see the winning values.--dsn; Django management commands use --database.No logs available
REPROQ_LOGS_DIR (or --logs-dir) is set on the worker.uv run python manage.py reproq logs --id <result_id>.