Queue & Background Jobs

Choose how TruCMS processes background work and set up the worker required by non-Sync queue drivers.

Queue settings tab in TruCMS with the Queue Driver selector

The Queue tab selects how background work is handed off. Sync is the only option that does not require a separate queue worker.

Why TruCMS has a queue

Some work does not need to finish inside the same browser request that started it. A queue lets TruCMS move eligible work into the background so a customer or administrator does not have to wait for every slow operation before the page can continue.

The Queue tab is inside Settings → General. Start with Sync unless you know your server can run a persistent queue worker. The other drivers are useful on busier sites, but selecting one without starting a worker will leave queued work waiting instead of being processed.

Changing the Queue Driver is not the whole setup

Database, Beanstalkd, Redis and Amazon SQS all require a continuously running queue worker. Configure the service and worker first, then switch the Queue Driver.

Choose the right Queue Driver

DriverBest fitWhat you must prepare
Sync (default)Shared hosting, small sites, or sites without background-process access.No worker. Queued work runs immediately as part of the request.
DatabaseA simple background queue when the server can run a persistent process but you do not want another service.Keep the application database healthy and run a queue worker continuously.
BeanstalkdServers already using a Beanstalkd queue service.Working Beanstalkd service and a persistent queue worker. Connection details are server-level configuration.
RedisSites already using Redis or needing a fast shared queue.Reachable Redis service, Redis connection details, queue name, and a persistent worker.
Amazon Simple Queue Service (SQS)Sites that want an AWS-managed queue instead of operating a queue server.SQS queue, AWS credentials/region/prefix/queue name, and a persistent worker.

Sync: simplest setup

Sync is the safest choice when your hosting account cannot keep a command running continuously. There are no additional fields and no worker to manage. The trade-off is that background-capable work runs while the current web request is still open, so slower tasks can make the user wait longer.

  1. Open Settings → General → Queue.
  2. Select Sync (default).
  3. Save the settings.

Database queue

The Database driver stores pending jobs in the TruCMS database. It avoids a separate queue service and is often the easiest move away from Sync on a VPS or managed server.

  1. Make sure your server or hosting plan can run a persistent background process.
  2. Start a queue worker from the TruCMS project folder using the command shown below.
  3. Open Settings → General → Queue, choose Database, and save.
  4. Trigger a normal action that creates background work and confirm the worker stays running without errors.

The application already includes the database storage it needs for queued jobs; you do not need to create a separate queue database.

Beanstalkd queue

Choose Beanstalkd only when the server already provides a Beanstalkd service. TruCMS does not expose Beanstalkd host/port fields on the Queue tab, so the server administrator must prepare that connection before you select the driver.

  1. Install or enable Beanstalkd on the server, or obtain the connection information from your host.
  2. Have the server administrator configure the TruCMS Beanstalkd connection.
  3. Start the persistent queue worker.
  4. Select Beanstalkd in the Queue tab and save.

Redis queue

Redis is a good choice when a fast Redis service is already part of your hosting stack. TruCMS asks for the Redis Queue Name on the Queue tab. The Redis server connection itself must also be available to the application.

Redis queue configuration fields in TruCMS

Choosing Redis reveals the Redis-specific queue options. A reachable Redis service and a running worker are still required.

  1. Confirm Redis is installed/reachable from the web server.
  2. Configure the Redis host, port and authentication used by TruCMS. If you also use Redis for the Cache Driver, those connection fields are available on the Cache settings page.
  3. Choose Redis on the Queue tab and set Redis Queue Name (normally the default queue unless your server administrator specifies another name).
  4. Start the queue worker and save the settings.

Redis queue with a different cache driver

If Cache is set to File, APC, Memcached or Database, the Redis connection still has to be configured at the server/application environment level. Ask the server administrator to do that before switching the queue.

Amazon SQS queue

Amazon SQS keeps the queue service in AWS. Create the queue in the AWS account first, then copy the matching values into TruCMS.

Amazon SQS queue configuration fields in TruCMS with credentials blanked

Choosing Amazon SQS reveals the queue connection fields. Keep access credentials private and run a persistent queue worker.

FieldWhat to enter
SQS Access Key IDAWS access key with permission to use the queue.
SQS Secret Access KeyThe secret paired with the access key.
SQS PrefixThe account/region queue URL prefix supplied by AWS.
SQS Queue NameThe exact SQS queue name.
SQS RegionThe AWS region where the queue exists.
  1. Create the SQS queue and least-privilege AWS credentials for it.
  2. Open Settings → General → Queue and select Amazon Simple Queue Service (SQS).
  3. Enter the five SQS values and save.
  4. Start the persistent queue worker and confirm it can consume jobs.

S3 uploads and SQS share AWS credential settings

The Uploading page's Amazon S3 configuration and the Queue tab's SQS configuration use the same AWS access key, secret and default region values. If both are enabled, use credentials/region that are valid for both services or coordinate the configuration with your server administrator before changing either page.

Run the queue worker

For every non-Sync driver, keep a queue worker running from the TruCMS project folder. A typical worker command is:

php artisan queue:work --sleep=3 --tries=3 --timeout=90

On a VPS, use a process manager such as Supervisor or systemd so the worker restarts after a reboot or failure. On managed hosting, use the host's background-worker feature if one is available. If your plan cannot run a persistent worker, keep the Queue Driver on Sync.

Restart workers after a TruCMS update

A long-running worker keeps the application loaded in memory. Restart the managed worker after updating TruCMS so it starts with the new application files.

Do not confuse the queue worker with cron

The queue worker processes pending background jobs. The Scheduled Tasks (Cron) entry checks which recurring TruCMS tasks are due. Sites using background queues commonly need both services running.

Troubleshooting a queue that appears stuck