[#2977] Document new background job system.

ckan/config/supervisor-ckan-worker.conf

@@ -0,0 +1,43 @@
+; =======================================================
+; Supervisor configuration for CKAN background job worker
+; =======================================================
+
+; 1. Copy this file to /etc/supervisr/conf.d
+; 2. Make sure the paths below match your setup
+
+
+[program:ckan-worker]
+
+; Use the full paths to the virtualenv and your configuration file here.
+command=/usr/lib/ckan/default/bin/paster --plugin=ckan jobs worker --config=/etc/ckan/default/production.ini
+
+
+; User the worker runs as.
+user=www-data
+
+
+; Start just a single worker. Increase this number if you have many or
+; particularly long running background jobs.
+numprocs=1
+process_name=%(program_name)s-%(process_num)02d
+
+
+; Log files.
+stdout_logfile=/var/log/ckan-worker.log
+stderr_logfile=/var/log/ckan-worker.log
+
+
+; Make sure that the worker is started on system start and automatically
+; restarted if it crashes unexpectedly.
+autostart=true
+autorestart=true
+
+
+; Number of seconds the process has to run before it is considered to have
+; started successfully.
+startsecs=10
+
+; Need to wait for currently executing tasks to finish at shutdown.
+; Increase this if you have very long running tasks.
+stopwaitsecs = 600
+

ckan/lib/cli.py

@@ -947,7 +947,7 @@ def purge(self, dataset_ref):
 
 
 class Celery(CkanCommand):
-    '''Celery daemon
+    '''Celery daemon [DEPRECATED]
 
     This command is DEPRECATED, use `paster jobs` instead.
 
@@ -2602,7 +2602,9 @@ class JobsCommand(CkanCommand):
 
         paster jobs cancel ID
 
-                Cancel a specific job.
+                Cancel a specific job. Jobs can only be canceled while they are
+                enqueued. Once a worker has started executing a job it cannot
+                be aborted anymore.
 
         paster jobs clear [QUEUES]
 

doc/api/index.rst

@@ -1,3 +1,5 @@
+.. _action api:
+
 =========
 API guide
 =========

doc/extensions/best-practices.rst

@@ -74,6 +74,10 @@ the name of your extension. For example:
   with the name of your extension. For example
   ``my_extension_foobarize_everything``.
 
+* The names of *background job queues* introduced by your extension should
+  begin with the name of your extension. For example
+  ``my_extension:super-special-job-queue``.
+
 In some situations, resources like databases may even be shared between
 multiple CKAN *instances*, which requires an even higher degree of uniqueness
 for the corresponding names. In that case, you should also prefix your