Your Auth Project¶
Overview¶
When installing Alliance Auth you are instructed to run the allianceauth start
command which generates a folder containing your auth project. This auth project is based off Alliance Auth but can be customized how you wish.
The myauth Folder¶
The first folder created is the root directory of your auth project. This folder contains:
- the
manage.py
management script used to interact with Django - a preconfigured
supervisor.conf
Supervisor config for running Celery (and optionally Gunicorn) automatically - a
log
folder which contains log files generated by Alliance Auth
The myauth Subfolder¶
Within your auth project root folder is another folder of the same name (a quirk of Django project structures). This folder contains:
- a Celery app definition in
celery.py
for registering tasks with the background workers - a web server gateway interface script
wsgi.py
for processing web requests - the root URL config
urls.py
which Django uses to direct requests to the appropriate view
There are also two subfolders for static
and templates
which allow adding new content and overriding default content shipped with Alliance Auth or Django.
And finally the settings folder.
Settings Files¶
With the settings folder lives two settings files: base.py
and local.py
The base settings file contains everything needed to run Alliance Auth. It handles configuration of Django and Celery, defines logging, and many other Django-required settings. This file should not be edited. While updating Alliance Auth you may be instructed to update the base settings file - this is achieved through the allianceauth update
command which overwrites the existing base settings file.
The local settings file is referred to as “your auth project’s settings file” and you are instructed to edit it during the install process. You can add any additional settings required by other apps to this file. Upon creation the first line is from .base import *
meaning all settings defined in the base settings file are loaded. You can override any base setting by simply redefining it in your local settings file.
Log Files¶
Your auth project comes with four log file definitions by default. These are created in the myauth/log/
folder at runtime.
allianceauth.log
contains allINFO
level and above logging messages from Alliance Auth. This is useful for tracking who is making changes to the site, what is happening to users, and debugging any errors that may occur.worker.log
contains logging messages from the Celery background task workers. This is useful for monitoring background processes such as group syncing to services.beat.log
contains logging messages from the background task scheduler. This is of limited use unless the scheduler isn’t starting.gunicorn.log
contains logging messages from Gunicorn workers. This contains all web-sourced messages found inallianceauth.log
as well as runtime errors from the workers themselves.
When asking for assistance with your auth project be sure to first read the logs, and share any relevant entries.
Custom Static and Templates¶
Within your auth project exists two folders named static
and templates
. These are used by Django for rendering web pages. Static refers to content Django does not need to parse before displaying, such as CSS styling or images. When running via a WSGI worker such as Gunicorn static files are copied to a location for the web server to read from. Templates are always read from the template folders, rendered with additional context from a view function, and then displayed to the user.
You can add extra static or templates by putting files in these folders. Note that changes to static requires running the python manage.py collectstatic
command to copy to the web server directory.
It is possible to overload static and templates shipped with Django or Alliance Auth by including a file with the exact path of the one you wish to overload. For instance if you wish to add extra links to the menu bar by editing the template, you would make a copy of the allianceauth/templates/allianceauth/base.html
file to myauth/templates/allinceauth/base.html
and edit it there. Notice the paths are identical after the templates/
directory - this is critical for it to be recognized. Your custom template would be used instead of the one included with Alliance Auth when Django renders the web page. Similar idea for static: put CSS or images at an identical path after the static/
directory and they will be copied to the web server directory instead of the ones included.
Custom URLs and Views¶
It is possible to add or override URLs with your auth project’s URL config file. Upon install it is of the form:
import allianceauth.urls
urlpatterns = [
url(r'', include(allianceauth.urls)),
]
This means every request gets passed to the Alliance Auth URL config to be interpreted.
If you wanted to add a URL pointing to a custom view, it can be added anywhere in the list if not already used by Alliance Auth:
import allianceauth.urls
import myauth.views
urlpatterns = [
url(r'', include(allianceauth.urls)),
url(r'myview/$', myauth.views.myview, name='myview'),
]
Additionally you can override URLs used by Alliance Auth here:
import allianceauth.urls
import myauth.views
urlpatterns = [
url(r'account/login/$', myauth.views.login, name='auth_login_user'),
url(r'', include(allianceauth.urls)),
]
Adding and Removing Apps¶
Your auth project is just a regular Django project - you can add in other Django apps as desired. Most come with dedicated setup guides, but in general:
- add
'appname',
to yourINSTALLED_APPS
setting - run
python manage.py migrate
- run
python manage.py collectstatic
If you ever want to remove an app, you should first clear it from the database to avoid dangling foreign keys: python manage.py migrate appname zero
. Then you can remove it from your auth project’s INSTALLED_APPS
list.