Mathis/allianceauth
1
0
Fork 0
mirror of https://gitlab.com/allianceauth/allianceauth.git synced 2025-12-18 23:05:07 +01:00
Code Issues Packages Projects Releases Wiki Activity

Documentation overhaul

Browse Source
This commit is contained in:
Erik Kalkoken
2020-03-05 02:23:58 +00:00
committed by Ariel Rin
parent 9c880eae8a
commit 8137f1023a
84 changed files with 844 additions and 530 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/maintenance/apps.md Normal file
View File

@@ -0,0 +1,10 @@
# Adding and Removing Apps
Your auth project is just a regular Django project - you can add in [other Django apps](https://djangopackages.org/) as desired. Most come with dedicated setup guides, but here is the general procedure:
1. add `'appname',` to your `INSTALLED_APPS` setting in `local.py`
2. run `python manage.py migrate`
3. run `python manage.py collectstatic`
4. restart AA with `supervisorctl restart myauth:`
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.

64
docs/maintenance/customizing.md Normal file
View File

@@ -0,0 +1,64 @@
# Customizing
It is possible to customize your **Alliance Auth** instance.
```eval_rst
.. warning::
Keep in mind that you may need to update some of your customizations manually after new release (e.g. when replacing AA templates).
```
## Site name
You can replace the default name shown on the web site with your own, e.g. the name of your Alliance.
Just update `SITE_NAME` in your `local.py` settings file accordingly, e.g.:
```python
SITE_NAME = 'Awesome Alliance'
```
## 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:
```python
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:
```python
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:
```python
import allianceauth.urls
import myauth.views
urlpatterns = [
url(r'account/login/$', myauth.views.login, name='auth_login_user'),
url(r'', include(allianceauth.urls)),
]
```

6
docs/maintenance/index.md
View File

@@ -1,9 +1,13 @@
# Maintenance
# Maintenance & Customizing
In the maintenance chapter you find details about where important log files are found, how you can customize your AA installation and how to solve common issues.
```eval_rst
.. toctree::
:maxdepth: 1
apps
customizing
project
troubleshooting

87
docs/maintenance/project.md
View File

@@ -1,28 +1,28 @@
# Your Auth Project
## Overview
# Folder structure
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 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
- 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
- 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
## Settings Files
With the settings folder lives two settings files: `base.py` and `local.py`
@@ -34,64 +34,9 @@ The local settings file is referred to as "your auth project's settings file" an
Your auth project comes with four log file definitions by default. These are created in the `myauth/log/` folder at runtime.
- `allianceauth.log` contains all `INFO` 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 in `allianceauth.log` as well as runtime errors from the workers themselves.
- `allianceauth.log` contains all `INFO` 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 in `allianceauth.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](https://djangopackages.org/) as desired. Most come with dedicated setup guides, but in general:
- add `'appname',` to your `INSTALLED_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.

22
docs/maintenance/troubleshooting.md
View File

@@ -1,13 +1,5 @@
# Troubleshooting
## Something broken? Stuck on an issue? Can't get it set up?
Start by checking the [issues](https://gitlab.com/allianceauth/allianceauth/issues?scope=all&utf8=%E2%9C%93&state=all&search=my+issue) - especially closed ones.
No answer?
- open an [issue](https://gitlab.com/allianceauth/allianceauth/issues)
- harass us on [gitter](https://gitter.im/R4stl1n/allianceauth)
## Logging
In its default configuration your auth project logs INFO and above messages to myauth/log/allianceauth.log. If you're encountering issues it's a good idea to view DEBUG messages as these greatly assist the troubleshooting process. These are printed to the console with manually starting the webserver via `python manage.py runserver`.
@@ -32,8 +24,10 @@ Make sure the background processes are running: `supervisorctl status myauth:`.
Stop celery workers with `supervisorctl stop myauth:worker` then clear the queue:
```bash
redis-cli FLUSHALL
celery -A myauth worker --purge
```
Press Control+C once.
@@ -50,3 +44,15 @@ This is likely due to a permissions mismatch. Check the setup guide for your web
### Unable to execute 'gunicorn myauth.wsgi' or ImportError: No module named 'myauth.wsgi'
Gunicorn needs to have context for its running location, `/home/alllianceserver/myauth/gunicorn myauth.wsgi` will not work, instead `cd /home/alllianceserver/myauth` then `gunicorn myauth.wsgi` is needed to boot Gunicorn. This is handled in the Supervisor config, but this may be encountered running Gunicorn manually for testing.
### Specified key was too long error
Migrations may about with the following error message:
```bash
Specified key was too long; max key length is 767 bytes
```
This error will occur if one is trying to use Maria DB prior to 10.2.x, which is not compatible with Alliance Auth.
Install a never Maria DB version to fix this issue another DBMS supported by Django 2.2.