Self-hosting

LessorMQ is a PHP application (Symfony) with MariaDB for messages and Redis for caches and coordination. The application nodes keep no state of their own, so you run as many as you need behind a load balancer.

Requirements

  • PHP 8.4 with pdo_mysql, served by PHP-FPM behind nginx (or any FastCGI server).
  • MariaDB 10.6 or newer. Claims rely on SKIP LOCKED, and the migrations on MariaDB's online schema changes; MySQL is not supported.
  • Redis 6 or newer (or Valkey): queue settings cache, pause state, sweep throttling, usage counters. Losing Redis loses nothing that matters; it is rebuilt from MariaDB.

Configuration

Environment variables:

Variable
APP_ENV prod
APP_SECRET a random string
DATABASE_QUEUE_URL mysql://user:password@host:3306/lessormq?serverVersion=mariadb-10.11.0&charset=utf8mb4
REDIS_URL redis://host:6379
LEASE_SWEEP_SECONDS how often, at most, a queue's expired leases are ended (default 60)
LEGACY_TENANT, LEGACY_TIMEZONE only for the pre-v1 API

Setting up

bin/console doctrine:migrations:migrate --no-interaction
bin/console lessormq:operator-key:create --name=admin

The second command prints an operator key once. Use it to create tenants:

curl -X POST https://mq.example.com/v1/tenants \
  -H "Authorization: Bearer $OPERATOR_KEY" -H 'Content-Type: application/json' \
  -d '{"name": "Acme"}'

The answer holds the tenant's first admin key, again shown once. Migrations are safe to run on every deploy, before the new version starts serving: they change the schema online, without locking the messages table.

To try LessorMQ locally, docker compose up in the repository starts a server with MariaDB and Redis on port 18080 (see the quickstart).

Scheduled jobs

Command How often
bin/console app:purge-old-messages every 15 minutes removes finished messages past their queue's retention
bin/console lessormq:tenants:reap hourly removes the data of deleted tenants

What to expose

Expose /v1/* and /healthz. Keep /metrics for your monitoring only: it lists every tenant's queues. The pre-v1 paths (/queues, /messages, /dashboard) have no authentication; block them unless you still run pre-v1 workers, and then only inside your network.

Sizing

  • Application nodes. A request takes a few milliseconds of CPU. A claim with wait_seconds holds a PHP worker for as long as it waits, so size the FPM pool for the number of workers that wait at the same time, or have workers wait less (5 seconds is a good default for most). Waiting checks for new work once a second.
  • MariaDB. An empty claim is one indexed read; a claim that gets a message is a short transaction on one row. The messages table holds open messages plus finished ones for their retention, so retention drives its size more than throughput does.
  • Redis. Small: a few keys per queue.

Monitoring

GET /metrics serves Prometheus metrics for every queue with open messages:

Metric
dbqueue_messages{tenant,queue,state} open messages: ready, delayed, processing
dbqueue_oldest_ready_seconds{tenant,queue} how long the oldest ready message has waited
dbqueue_oldest_processing_seconds{tenant,queue} how long the longest lease has been held
dbqueue_max_retry_count{tenant,queue} the highest attempt count among open messages
dbqueue_paused{tenant,queue} 1 while the queue is paused
dbqueue_legacy_requests_total{route} calls to the pre-v1 API

Queues get stuck as an age, not as a count: a long queue that drains is fine, a short one whose head never moves is not.

groups:
  - name: lessormq
    rules:
      - alert: LessorMQQueueStuck
        expr: dbqueue_oldest_ready_seconds > 900 and on(tenant, queue) dbqueue_paused == 0
        for: 5m
        annotations:
          summary: "{{ $labels.tenant }}/{{ $labels.queue }}: nothing has taken work for 15 minutes"
      - alert: LessorMQLeaseHeldLong
        expr: dbqueue_oldest_processing_seconds > 3600
        for: 10m
        annotations:
          summary: "{{ $labels.tenant }}/{{ $labels.queue }}: a message has been processing for over an hour"
      - alert: LessorMQPausedLong
        expr: dbqueue_paused == 1
        for: 1d
        annotations:
          summary: "{{ $labels.tenant }}/{{ $labels.queue }} has been paused for a day"

/healthz answers 200 while MariaDB and Redis are reachable, 503 otherwise; use it for readiness checks.