Template supervisor conf.

Update docs to reflect simple installation.

Ensure allianceauth celery workers can find config file for development (doesn't work as celeryapp.py).

allianceauth/bin/allianceauth.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
 import os
+import sys
 from optparse import OptionParser
 from django.core.management import ManagementUtility
 
@@ -40,6 +41,8 @@ def create_project(parser, options, args):
     utility_args = ['django-admin.py',
                     'startproject',
                     '--template=' + template_path,
+                    '--pythonpath=' + '/'.join(sys.executable.split('/')[:-1]),
+                    '--ext=conf',
                     project_name]
 
     if dest_dir:

allianceauth/celery.py

@@ -0,0 +1,16 @@
+import os
+from celery import Celery
+
+# set the default Django settings module for the 'celery' program.
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'allianceauth.project_template.project_name.settings.base')
+
+from django.conf import settings  # noqa
+
+app = Celery('alliance_auth')
+
+# Using a string here means the worker don't have to serialize
+# the configuration object to child processes.
+app.config_from_object('django.conf:settings')
+
+# Load task modules from all registered Django app configs.
+app.autodiscover_tasks(lambda: settings.INSTALLED_APPS)

allianceauth/project_template/celeryapp.py

@@ -2,11 +2,11 @@ import os
 from celery import Celery
 
 # set the default Django settings module for the 'celery' program.
-os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'alliance_auth.settings')
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', '{{ project_name }}.settings.local')
 
 from django.conf import settings  # noqa
 
-app = Celery('alliance_auth')
+app = Celery('{{ project_name }}')
 
 # Using a string here means the worker don't have to serialize
 # the configuration object to child processes.

allianceauth/project_template/supervisor.conf

@@ -0,0 +1,36 @@
+[program:beat]
+command={{ pythonpath}}/celery -A {{ project_name }} beat
+directory={{ project_directory }}
+user=allianceserver
+stdout_logfile={{ project_directory }}/log/beat.log
+stderr_logfile={{ project_directory }}/log/beat.log
+autostart=true
+autorestart=true
+startsecs=10
+priority=998
+
+[program:worker]
+command={{ pythonpath}}/celery -A {{ project_name }} worker
+directory={{ project_directory }}
+user=allianceserver
+numprocs=1
+stdout_logfile={{ project_directory }}/log/worker.log
+stderr_logfile={{ project_directory }}/log/worker.log
+autostart=true
+autorestart=true
+startsecs=10
+stopwaitsecs = 600
+killasgroup=true
+priority=998
+
+[program:gunicorn]
+user = allianceserver
+directory={{ project_directory }}
+command={{ pythonpath}}/gunicorn {{ project_name}}.wsgi --workers=3 --timeout 120
+autostart=true
+autorestart=true
+stopsignal=INT
+
+[group:{{ project_name }}]
+programs=beat,worker,gunicorn
+priority=999

docs/installation/auth/allianceauth.md

@@ -1,7 +1,7 @@
 # Alliance Auth Installation
 
 ```eval_rst
-.. important::
+.. tip::
    Installation is easiest as the root user. Log in as root or a user with sudo powers.
 ```
 
@@ -132,9 +132,49 @@ And finally ensure the allianceserver user has read/write permissions to this di
 
     chown -R allianceserver:allianceserver /home/allianceserver/myauth
 
+## Background Tasks
+
+### Gunicorn
+
+To run the auth website a [WSGI Server](https://www.fullstackpython.com/wsgi-servers.html) is required. [Gunicorn](http://gunicorn.org/) is highly recommended for its ease of configuring. Installation is simple: `pip install gunicorn`. It can be manually called with `gunicorn myauth.wsgi` or automatically run using supervisor.
+
+Additional information is available in the [gunicorn](gunicorn.md) doc.
+
+### Supervisor
+
+[Supervisor](http://supervisord.org/) is a process watchdog service: it makes sure other processes are started automatically and kept running. It can be used to automatically start the WSGI server and celery workers for background tasks. Installation varies by OS:
+
+Ubuntu:
+
+    apt-get install supervisor
+
+CentOS:
+
+    yum install supervisor
+    systemctl enable supervisord.service
+    systemctl start supervisord.service
+
+Once installed it needs a configuration file to know which processes to watch. Your Alliance Auth project comes with a ready-to-use template which will ensure the celery workers, celery task scheduler and gunicorn are all running.
+
+    ln /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
+    supervisorctl reload
+
+You can check the status of the processes with `supervisorctl status`. Logs from these processes are available in `/home/allianceserver/myauth/log` named by process.
+
+```eval_rst
+.. note::
+   Any time the code or your settings change you'll need to restart gunicorn and celery. ::
+   
+       supervisorctl restart myauth:
+```
+
+## Webserver
+
+Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md) and follow the respective guide.
+
 ## Superuser
 
-Before proceeding it is essential to create a superuser account. This account will have all permissions in Alliance Auth. It's OK to use this as your personal auth account.
+Before using your auth site it is essential to create a superuser account. This account will have all permissions in Alliance Auth. It's OK to use this as your personal auth account.
 
     python /home/allianceserver/myauth/manage.py createsuperuser
 
@@ -143,11 +183,6 @@ Before proceeding it is essential to create a superuser account. This account wi
    Be sure to add a main character to this account before attempting to activate services with it.
 ```
 
-## Webserver
-
-Once installed, move onto the [Gunicorn Guide](gunicorn.md) and decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md). You will also need to install [supervisor](supervisor.md) to run the background tasks.
-
-
 ## Updating
 
 Periodically [new releases](https://github.com/allianceauth/allianceauth/releases/) are issued with bug fixes and new features. To update your install, simply activate your virtual environment and update with `pip install --upgrade allianceauth`. Be sure to read the release notes which will highlight changes.

docs/installation/auth/gunicorn.md

@@ -15,30 +15,30 @@ Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html
 
 Install Gunicorn using pip, `pip install gunicorn`.
 
-In your `allianceauth` base directory, try running `gunicorn --bind 0.0.0.0:8000 alliance_auth.wsgi`. You should be able to browse to http://yourserver:8000 and see your Alliance Auth installation running. Images and styling will be missing, but dont worry, your web server will provide them.
+In your `myauth` base directory, try running `gunicorn --bind 0.0.0.0:8000 myauth.wsgi`. You should be able to browse to http://yourserver:8000 and see your Alliance Auth installation running. Images and styling will be missing, but dont worry, your web server will provide them.
 
 Once you validate its running, you can kill the process with Ctrl+C and continue.
 
 ## Running Gunicorn with Supervisor
 
-You should use [Supervisor](supervisor.md) to keep all of Alliance Auth components running (instead of using screen). You don't _have to_ but we will be using it to start and run Gunicorn so you might as well.
+You should use [Supervisor](allianceauth.md#supervisor) to keep all of Alliance Auth components running (instead of using screen). You don't _have to_ but we will be using it to start and run Gunicorn so you might as well.
 
 ### Sample Supervisor config
-You'll want to edit `/etc/supervisor/conf.d/aauth_gunicorn.conf` (or whatever you want to call the config file)
+You'll want to edit `/etc/supervisor/conf.d/myauth_gunicorn.conf` (or whatever you want to call the config file)
 ```
-[program:aauth-gunicorn]
+[program:myauth-gunicorn]
-user = www-data
+user = allianceserver
-directory=/home/allianceserver/allianceauth/
+directory=/home/allianceserver/myauth/
-command=gunicorn alliance_auth.wsgi --workers=3 --timeout 120
+command=gunicorn myauth.wsgi --workers=3 --timeout 120
 autostart=true
 autorestart=true
 stopsignal=INT
 ```
 
-- `[program:aauth-gunicorn]` - Change aauth-gunicorn to whatever you wish to call your process in Supervisor.
+- `[program:myauth-gunicorn]` - Change myauth-gunicorn to whatever you wish to call your process in Supervisor.
-- `user = www-data` - Change to whatever user you wish Gunicorn to run as. You could even set this as allianceserver if you wished. I'll leave the question security of that up to you.
+- `user = allianceserver` - Change to whatever user you wish Gunicorn to run as. You could even set this as allianceserver if you wished. I'll leave the question security of that up to you.
-- `directory=/home/allianceserver/allianceauth/` - Needs to be the path to your Alliance Auth install.
+- `directory=/home/allianceserver/myauth/` - Needs to be the path to your Alliance Auth project.
-- `command=gunicorn alliance_auth.wsgi --workers=3 --timeout 120` - Running Gunicorn and the options to launch with. This is where you have some decisions to make, we'll continue below.
+- `command=gunicorn myauth.wsgi --workers=3 --timeout 120` - Running Gunicorn and the options to launch with. This is where you have some decisions to make, we'll continue below.
 
 #### Gunicorn Arguments
 
@@ -118,4 +118,4 @@ Any web server capable of proxy passing should be able to sit in front of Gunico
 ## Restarting Gunicorn
 In the past when you made changes you restarted the entire Apache server. This is no longer required. When you update or make configuration changes that ask you to restart Apache, instead you can just restart Gunicorn:
 
-`sudo supervisorctl restart aauth-gunicorn`, or the service name you chose for it.
+`sudo supervisorctl restart myauth-gunicorn`, or the service name you chose for it.

docs/installation/auth/index.md

@@ -7,5 +7,4 @@
     gunicorn
     nginx
     apache
-    supervisor
 ```

docs/installation/auth/supervisor.md

@@ -1,81 +0,0 @@
-# Supervisor
-
->Supervisor is a client/server system that allows its users to control a number of processes on UNIX-like operating systems.
-
-What that means is supervisor will take care of ensuring the celery workers are running (and mumble authenticator) and start the automatically on reboot. Handy, eh?
-
-## Installation
-
-Most OSes have a supervisor package available in their distribution.
-
-Ubuntu:
-
-    sudo apt-get install supervisor
-
-CentOS:
-
-    sudo yum install supervisor
-    sudo systemctl enable supervisord.service
-    sudo systemctl start supervisord.service
-
-## Configuration
-
-Auth provides example config files for the celery workers, the periodic task scheduler (celery beat), and the mumble authenticator. All of these are available in `thirdparty/Supervisor`.
-
-For most users, all you have to do is copy the config files to `/etc/supervisor/conf.d` then restart the service. Copy `auth.conf` for the celery workers, and `auth-mumble.conf` for the mumble authenticator. For all three just use a wildcard:
-
-    sudo cp thirdparty/Supervisor/* /etc/supervisor/conf.d
-
-Ubuntu:
-
-    sudo service supervisor restart
-
-CentOS:
-
-    sudo systemctl restart supervisor.service
-
-## Checking Status
-
-To ensure the processes are working, check their status:
-
-    sudo supervisorctl status
-
-Processes will be `STARTING`, `RUNNING`, or `ERROR`. If an error has occurred, check their log files:
- - celery workers: `log/worker.log`
- - celery beat: `log/beat.log`
- - authenticator: `log/authenticator.log`
- 
-## Restarting Processes
-
-To restart the celery group:
-
-    sudo supervisorctl restart auth:*
-
-To restart just celerybeat:
-
-    sudo supervisorctl restart auth:celerybeat
-
-To restart just celeryd:
-
-    sudo supervisorctl restart auth:celeryd
-
-To restart just mumble authenticator:
-
-    sudo supervisorctl restart auth-mumble
-
-## Customizing Config Files
-
-The only real customization needed is if running in a virtual environment. The python path will have to be changed in order to start in the venv.
-
-Edit the config files and find the line saying `command`. Replace `python` with `/path/to/venv/bin/python`. For Celery replace `celery` with `/path/to/venv/bin/celery`. This can be relative to the `directory` specified in the config file.
-
-Note that for config changes to be loaded, the supervisor service must be restarted.
-
-## Troubleshooting
-
-### auth-celerybeat fails to start
-Most often this is caused by a permissions issue on the allianceauth directory (the error will talk about `celerybeat.pid`). The easiest fix is to edit its config file and change the `user` from `allianceserver` to `root`.
-
-### Workers are using old settings
-
-Every time the codebase is updated or settings file changed, workers will have to be restarted. Easiest way is to restart the supervisor service (see configuration above for commands)