From 3f33485ca91b3e5dd37592430eeaf5be9aac61c1 Mon Sep 17 00:00:00 2001 From: Adarnof Date: Tue, 10 Oct 2017 00:29:57 -0400 Subject: [PATCH] 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 | 3 + allianceauth/celery.py | 16 ++++ .../{ => project_template}/celeryapp.py | 4 +- allianceauth/project_template/supervisor.conf | 36 +++++++++ docs/installation/auth/allianceauth.md | 49 +++++++++-- docs/installation/auth/gunicorn.md | 24 +++--- docs/installation/auth/index.md | 1 - docs/installation/auth/supervisor.md | 81 ------------------- 8 files changed, 111 insertions(+), 103 deletions(-) create mode 100644 allianceauth/celery.py rename allianceauth/{ => project_template}/celeryapp.py (77%) create mode 100644 allianceauth/project_template/supervisor.conf delete mode 100644 docs/installation/auth/supervisor.md diff --git a/allianceauth/bin/allianceauth.py b/allianceauth/bin/allianceauth.py index 6bf70cb1..7aed897f 100644 --- a/allianceauth/bin/allianceauth.py +++ b/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: diff --git a/allianceauth/celery.py b/allianceauth/celery.py new file mode 100644 index 00000000..63c652e0 --- /dev/null +++ b/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) diff --git a/allianceauth/celeryapp.py b/allianceauth/project_template/celeryapp.py similarity index 77% rename from allianceauth/celeryapp.py rename to allianceauth/project_template/celeryapp.py index 49c2c809..dc9b4d39 100644 --- a/allianceauth/celeryapp.py +++ b/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. diff --git a/allianceauth/project_template/supervisor.conf b/allianceauth/project_template/supervisor.conf new file mode 100644 index 00000000..228b48db --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/installation/auth/allianceauth.md b/docs/installation/auth/allianceauth.md index 71e8c173..9b4579ed 100644 --- a/docs/installation/auth/allianceauth.md +++ b/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. diff --git a/docs/installation/auth/gunicorn.md b/docs/installation/auth/gunicorn.md index 60a6cdae..573ef0f4 100644 --- a/docs/installation/auth/gunicorn.md +++ b/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] -user = www-data -directory=/home/allianceserver/allianceauth/ -command=gunicorn alliance_auth.wsgi --workers=3 --timeout 120 +[program:myauth-gunicorn] +user = allianceserver +directory=/home/allianceserver/myauth/ +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. -- `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. -- `directory=/home/allianceserver/allianceauth/` - Needs to be the path to your Alliance Auth install. -- `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. +- `[program:myauth-gunicorn]` - Change myauth-gunicorn to whatever you wish to call your process in Supervisor. +- `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/myauth/` - Needs to be the path to your Alliance Auth project. +- `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. diff --git a/docs/installation/auth/index.md b/docs/installation/auth/index.md index d245828b..0a64cb11 100644 --- a/docs/installation/auth/index.md +++ b/docs/installation/auth/index.md @@ -7,5 +7,4 @@ gunicorn nginx apache - supervisor ``` diff --git a/docs/installation/auth/supervisor.md b/docs/installation/auth/supervisor.md deleted file mode 100644 index 276dfac0..00000000 --- a/docs/installation/auth/supervisor.md +++ /dev/null @@ -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)