Mathis/allianceauth
1
0
Fork 0
mirror of https://gitlab.com/allianceauth/allianceauth.git synced 2025-07-08 20:10:17 +02:00
Code Issues Packages Projects Releases Wiki Activity

[FIX] Grammar and spelling

Browse Source
This commit is contained in:
Peter Pfeufer 2023-12-17 20:07:14 +01:00
parent 8aeb061635
commit 6e3219fd1b
No known key found for this signature in database
GPG Key ID: 6051D2C6AD4EBC27
52 changed files with 422 additions and 424 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/contributing/index.md
View File

@ -1,12 +1,12 @@
# Contributing
Alliance Auth is developed by the community and we are always looking to welcome new contributors. If you are interested in contributing, here are some ideas where to start:
Alliance Auth is developed by the community, and we are always looking to welcome new contributors. If you are interested in contributing, here are some ideas where to start:
## Publish a new community app or service
One great way to contribute is to develop and publish your own community app or service for Alliance Auth. By design Auth only comes with some basic features and therefore heavily relies on the community to provide apps to extend Auth with additional features.
One great way to contribute is to develop and publish your own community app or service for Alliance Auth. By design, Auth only comes with some basic features and therefore heavily relies on the community to provide apps to extend Auth with additional features.
To publish your app make sure it can be installed from a public repo or PyPI. Once it's ready, you can inform everybody about your new app by posting it to our [list of community apps](/features/community/index.md).
To publish your app, make sure it can be installed from a public repo or PyPI. Once it's ready, you can inform everybody about your new app by posting it to our [list of community apps](/features/community/index.md).
If you are looking for ideas on what to make, you can check out Auth's [issue list](https://gitlab.com/allianceauth/allianceauth/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=enhancement). Many of those issues are feature requests that will probably never make into Auth core, but would be awesome to have as community app or service. You could also ask the other devs on our Discord server for ideas or to help you get a feeling about which new features might be in higher demand than others.
@ -16,7 +16,7 @@ There are quite a few great community apps that need help from additional mainta
Sometimes original app owners may even be looking to completely hand over their apps to a new owner.
If you are interested to help maintain an existing community app or service you can just start working on open issues and create merge requests. Or just ask other devs on our Discord.
If you are interested to help maintain an existing community app or service, you can start working on open issues and create merge requests. Or just ask other devs on our Discord.
## Help with improving Auth documentation
@ -26,7 +26,7 @@ Auth has an extensive [documentation](https://allianceauth.readthedocs.io/en/lat
One of the main functions of the Auth Discord server is to help the community with any support question they may have when installing or running an Auth installation.
Note that you do not need a be part of any official group to become a supporter. Just jump in and help with answering new questions from the community if you know how to help.
Note that you do not need to be part of any official group to become a supporter. Jump in and help with answering new questions from the community if you know how to help.
## Help to improve Alliance Auth core
@ -34,12 +34,12 @@ Alliance Auth has an issue list, which is usually the basis for all maintenance
We usually have a long list of open issues and very much welcome every help to fix existing bugs or work on new features for Auth.
Before starting to code on any topic we'd suggest talking to the other devs on Discord to make sure your issue is not already being worked on. Also, some feature request may be better implemented in a community app. Another aspect, which is best clarified by talking with the other devs.
Before starting to code on any topic, we'd suggest talking to the other devs on Discord to make sure your issue is not already being worked on. Also, some feature requests may be better implemented in a community app. Another aspect, which is best clarified by talking with the other devs.
If you like to contribute to Auth core, but are unsure where to start, we have a dedicated label for issues that are suitable for beginners: [beginner friendly](https://gitlab.com/allianceauth/allianceauth/-/issues?label_name%5B%5D=beginner+friendly).
If you like to contribute to Auth core, but are unsure where to start, we have a dedicated label for issues that are suitable for beginners: [beginner-friendly](https://gitlab.com/allianceauth/allianceauth/-/issues?label_name%5B%5D=beginner+friendly).
## Additional Resources
For more information on how to create community apps or how to setup a developer environment for Auth, please see our official [developer documentation](/development/index.md).
For more information on how to create community apps or how to set up a developer environment for Auth, please see our official [developer documentation](/development/index.md).
For getting in touch with other contributors please feel free to join the [Alliance Auth Discord server](https://discord.gg/fjnHAmk).
For getting in touch with other contributors, please feel free to join the [Alliance Auth Discord server](https://discord.gg/fjnHAmk).

22
docs/customizing/index.md
View File

@ -3,12 +3,12 @@
It is possible to customize your **Alliance Auth** instance.
:::{warning}
Keep in mind that you may need to update some of your customizations manually after new Auth releases (e.g. when replacing templates).
Keep in mind that you may need to update some of your customizations manually after new Auth releases (e.g., when replacing templates).
:::
## Site name
You can replace the default name shown on the web site with your own, e.g. the name of your Alliance.
You can replace the default name shown on the website with your own, e.g., the name of your Alliance.
Just update `SITE_NAME` in your `local.py` settings file accordingly, e.g.:
@ -18,15 +18,15 @@ 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.
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.
You can add extra static or templates by putting files in these folders. Note that changes to static require 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/allianceauth/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:
It is possible to add or override URLs with your auth project's URL config file. Upon installing, it is of the form:
```python
from django.urls import re_path
@ -56,7 +56,7 @@ urlpatterns = [
]
```
Additionally you can override URLs used by Alliance Auth here:
Additionally, you can override URLs used by Alliance Auth here:
```python
from django.urls import re_path
@ -73,13 +73,13 @@ urlpatterns = [
## Example: Adding an external link to the sidebar
As an example we are adding an external links to the Alliance Auth sidebar using the template overrides feature. For our example let's add a link to Google's start page.
As an example, we are adding an external links to the Alliance Auth sidebar using the template overrides feature. For example, let's add a link to Google's start page.
### Step 1 - Create the template override folder
First you need to create the folder for the template on your server. For AA to pick it up it has to match a specific structure.
First, you need to create the folder for the template on your server. For Alliance Auth to pick it up, it has to match a specific structure.
If you have a default installation you can create the folder like this:
If you have a default installation, you can create a folder like this:
```shell
mkdir -p /home/allianceserver/myauth/myauth/templates/allianceauth
@ -87,7 +87,7 @@ mkdir -p /home/allianceserver/myauth/myauth/templates/allianceauth
### Step 2 - Download the original template
Next you need to download a copy of the original template file we want to change. For that let's move into the above folder and then download the file into the current folder with:
Next, you need to download a copy of the original template file we want to change. For that, let's move into the above folder and then download the file into the current folder with:
```shell
cd /home/allianceserver/myauth/myauth/templates/allianceauth
@ -96,7 +96,7 @@ wget <https://gitlab.com/allianceauth/allianceauth/-/raw/master/allianceauth/tem
### Step 3 - Modify the template
Now you can modify the template to add your custom link. To create the google link we can add this snippet *between* the `{% menu_items %}` and the `</ul>` tag:
Now you can modify the template to add your custom link. To create the Google link, we can add this snippet *between* the `{% menu_items %}` and the `</ul>` tag:
```shell
nano /home/allianceserver/myauth/myauth/templates/allianceauth/side-menu.html

4
docs/development/aa_core/code-style.md
View File

@ -2,7 +2,7 @@
## Pre-Commit
Alliance Auth is a team effort with developers of various skill levels and background. To avoid significant drift or formatting changes between developers we use [pre-commit](https://pre-commit.com/) to apply a very minimal set of formatting checks to code contributed to the project.
Alliance Auth is a team effort with developers of various skill levels and background. To avoid significant drift or formatting changes between developers, we use [pre-commit](https://pre-commit.com/) to apply a very minimal set of formatting checks to code contributed to the project.
Pre-commit is also very popular with our Community Apps and may be significantly more opinionated or looser depending on the project.
@ -46,4 +46,4 @@ These can be used to automatically generate our Sphinx documentation in either f
It is advisable to avoid wide formatting changes on code that is not being modified by an MR. Further to this, automated code formatting should be kept to a minimal when modifying sections of existing files.
If you are contributing whole modules or rewriting large sections of code you may use any legible code formatting valid under Python.
If you are contributing whole modules or rewriting large sections of code, you may use any legible code formatting valid under Python.

8
docs/development/aa_core/documentation.md
View File

@ -11,8 +11,8 @@ allows for documentation to be maintained at different versions more easily.
## Building Documentation
If you're developing new documentation, its likely you'll want or need to test build it before committing to your
branch. To achieve this you can use Sphinx to build the documentation locally as it appears on Read the Docs.
If you're developing new documentation, it's likely you'll want or need to test build it before committing to your
branch. To achieve this, you can use Sphinx to build the documentation locally as it appears on Read the Docs.
Activate your virtual environment (if you're using one) and install the documentation requirements found in
`docs/requirements.txt` using pip, e.g. `pip install -r docs/requirements.txt`.
@ -35,5 +35,5 @@ reStructuredText here
```
````
Markdown is used elsewhere on Github so it provides the most portability of documentation from Issues and Pull Requests
as well as providing an easier initial migration path from the Github wiki.
Markdown is used elsewhere on GitHub, so it provides the most portability of documentation from Issues and Pull Requests
as well as providing an easier initial migration path from the GitHub wiki.

76
docs/development/custom/integrating-services.md
View File

@ -1,16 +1,16 @@
# Integrating Services
One of the primary roles of Alliance Auth is integrating with external services in order to authenticate and manage users. This is achieved through the use of service modules.
One of the primary roles of Alliance Auth is integrating with external services to authenticate and manage users. This is achieved through the use of service modules.
## The Service Module
Each service module is its own self contained Django app. It will likely contain views, models, migrations and templates. Anything that is valid in a Django app is valid in a service module.
Each service module is its own self-contained Django app. It will likely contain views, models, migrations and templates. Anything that is valid in a Django app is valid in a service module.
Normally service modules live in `services.modules` though they may also be installed as external packages and installed via `pip` if you wish. A module is installed by including it in the `INSTALLED_APPS` setting.
### Service Module Structure
Typically a service will contain 5 key components:
Typically, a service will contain 5 key components:
- [The Hook](#the-hook)
- [The Service Manager](#the-service-manager)
@ -36,11 +36,11 @@ The architecture looks something like this:
Module --▶ Dependency/Import
```
While this is the typical structure of the existing services modules, there is no enforcement of this structure and you are, effectively, free to create whatever architecture may be necessary. A service module need not even communicate with an external service, for example, if similar triggers such as validate_user, delete_user are required for a module it may be convenient to masquerade as a service. Ideally though, using the common structure improves the maintainability for other developers.
While this is the typical structure of the existing services modules, there is no enforcement of this structure, and you are, effectively, free to create whatever architecture may be necessary. A service module need not even communicate with an external service, for example, if similar triggers such as validate_user, delete_user are required for a module it may be convenient to masquerade as a service. Ideally, using the common structure improves the maintainability for other developers.
### The Hook
In order to integrate with Alliance Auth service modules must provide a `services_hook`. This hook will be a function that returns an instance of the `services.hooks.ServiceHook` class and decorated with the `@hooks.registerhook` decorator. For example:
To integrate with Alliance Auth service modules must provide a `services_hook`. This hook will be a function that returns an instance of the `services.hooks.ServiceHook` class and decorated with the `@hooks.registerhook` decorator. For example:
```python
@hooks.register('services_hook')
@ -61,7 +61,7 @@ class ExampleService(ServicesHook):
def __init__(self):
ServicesHook.__init__(self)
self.urlpatterns = urlpatterns
self.service_url = 'http://exampleservice.example.com'
self.service_url = 'https://exampleservice.example.com'
"""
Overload base methods here to implement functionality
@ -70,9 +70,9 @@ class ExampleService(ServicesHook):
### The ServiceHook class
The base `ServiceHook` class defines function signatures that Alliance Auth will call under certain conditions in order to trigger some action in the service.
The base `ServiceHook` class defines function signatures that Alliance Auth will call under certain conditions to trigger some action in the service.
You will need to subclass `services.hooks.ServiceHook` in order to provide implementation of the functions so that Alliance Auth can interact with the service correctly. All of the functions are optional, so its up to you to define what you need.
You will need to subclass `services.hooks.ServiceHook` in order to provide implementation of the functions so that Alliance Auth can interact with the service correctly. All the functions are optional, so its up to you to define what you need.
Instance Variables:
@ -103,7 +103,7 @@ Internal name of the module, should be unique amongst modules.
#### self.urlpatterns
You should define all of your service URLs internally, usually in `urls.py`. Then you can import them and set `self.urlpatterns` to your defined urlpatterns.
You should usually define all of your service URLs internally, in `urls.py`. Then you can import them and set `self.urlpatterns` to your defined urlpatterns.
```python
from . import urls
@ -122,13 +122,13 @@ This is provided as a courtesy and defines the default template to be used with
#### title
This is a property which provides a user friendly display of your service's name. It will usually do a reasonably good job unless your service name has punctuation or odd capitalization. If this is the case you should override this method and return a string.
This is a property which provides a user-friendly display of your service's name. It will usually do a reasonably good job unless your service name has punctuation or odd capitalization. If this is the case, you should override this method and return a string.
#### delete_user
`def delete_user(self, user, notify_user=False):`
Delete the users service account, optionally notify them that the service has been disabled. The `user` parameter should be a Django User object. If notify_user is set to `True` a message should be set to the user via the `notifications` module to alert them that their service account has been disabled.
Delete the user's service account, optionally notify them that the service has been disabled. The `user` parameter should be a Django User object. If notify_user is set to `True` a message should be set to the user via the `notifications` module to alert them that their service account has been disabled.
The function should return a boolean, `True` if successfully disabled, `False` otherwise.
@ -136,7 +136,7 @@ The function should return a boolean, `True` if successfully disabled, `False` o
`def validate_user(self, user):`
Validate the users service account, deleting it if they should no longer have access. The `user` parameter should be a Django User object.
Validate the user's service account, deleting it if they should no longer have access. The `user` parameter should be a Django User object.
An implementation will probably look like the following:
@ -155,7 +155,7 @@ This function will be called periodically on all users to validate that the give
`def sync_nickname(self, user):`
Very optional. As of writing only one service defines this. The `user` parameter should be a Django User object. When called, the given users nickname for the service should be updated and synchronized with the service.
Very optional. As of writing, only one service defines this. The `user` parameter should be a Django User object. When called, the given users nickname for the service should be updated and synchronized with the service.
If this function is defined, an admin action will be registered on the Django Users view, allowing admins to manually trigger this action for one or many users. The hook will trigger this action user by user, so you won't have to manage a list of users.
@ -165,7 +165,7 @@ If this function is defined, an admin action will be registered on the Django Us
Updates the nickname for a list of users. The `users` parameter must be a list of Django User objects.
If this method is defined, the admin action for updating service related nicknames for users will call this bulk method instead of sync_nickname. This gives you more control over how mass updates are executed, e.g. ensuring updates do not run in parallel to avoid causing rate limit violations from an external API.
If this method is defined, the admin action for updating service related nicknames for users will call this bulk method instead of sync_nickname. This gives you more control over how mass updates are executed, e.g., ensuring updates do not run in parallel to avoid causing rate limit violations from an external API.
This is an optional method.
@ -173,12 +173,12 @@ This is an optional method.
`def update_groups(self, user):`
Update the users group membership. The `user` parameter should be a Django User object.
When this is called the service should determine the groups the user is a member of and synchronize the group membership with the external service. If you service does not support groups then you are not required to define this.
Update the user's group membership. The `user` parameter should be a Django User object.
When this is called, the service should determine the groups the user is a member of and synchronize the group membership with the external service. If your service does not support groups, then you are not required to define this.
If this function is defined, an admin action will be registered on the Django Users view, allowing admins to manually trigger this action for one or many users. The hook will trigger this action user by user, so you won't have to manage a list of users.
This action is usually called via a signal when a users group membership changes (joins or leaves a group).
This action is usually called via a signal when a user's group membership changes (joins or leaves a group).
#### update_groups_bulk
@ -186,7 +186,7 @@ This action is usually called via a signal when a users group membership changes
Updates the group memberships for a list of users. The `users` parameter must be a list of Django User objects.
If this method is defined, the admin action for updating service related groups for users will call this bulk method instead of update_groups. This gives you more control over how mass updates are executed, e.g. ensuring updates do not run in parallel to avoid causing rate limit violations from an external API.
If this method is defined, the admin action for updating service related groups for users will call this bulk method instead of update_groups. This gives you more control over how mass updates are executed, e.g., ensuring updates do not run in parallel to avoid causing rate limit violations from an external API.
This is an optional method.
@ -204,7 +204,7 @@ I'm really not sure when this is called, it may have been a hold over from befor
Is this service active for the given user? The `user` parameter should be a Django User object.
Usually you wont need to override this as it calls `service_enabled_members` or `service_enabled_blues` depending on the users state.
Usually you won't need to override this as it calls `service_enabled_members` or `service_enabled_blues` depending on the user's state.
#### show_service_ctrl
@ -212,7 +212,7 @@ Usually you wont need to override this as it calls `service_enabled_members` or
Should the service be shown for the given `user` with the given `state`? The `user` parameter should be a Django User object, and the `state` parameter should be a valid state from `authentication.states`.
Usually you wont need to override this function.
Usually you won't need to override this function.
For more information see the [render_service_ctrl](#render_service_ctrl) section.
@ -222,7 +222,7 @@ For more information see the [render_service_ctrl](#render_service_ctrl) section
Render the services control row. This will be called for all active services when a user visits the `/services/` page and [show_service_ctrl](#show_service_ctrl) returns `True` for the given user.
It should return a string (usually from `render_to_string`) of a table row (`<tr>`) with 4 columns (`<td>`). Column #1 is the service name, column #2 is the users username for this service, column #3 is the services URL, and column #4 is the action buttons.
It should return a string (usually from `render_to_string`) of a table row (`<tr>`) with 4 columns (`<td>`). Column #1 is the service name, column #2 is the user's username for this service, column #3 is the services URL, and column #4 is the action buttons.
You may either define your own service template or use the default one provided. The default can be used like this example:
@ -248,61 +248,61 @@ def render_services_ctrl(self, request):
}, request=request)
```
the `Urls` class defines the available URL names for the 4 actions available in the default template:
the `Urls` class defines the available URL names for the four actions available in the default template:
- Activate (create service account)
- Deactivate (delete service account)
- Activate (create a service account)
- Deactivate (delete a service account)
- Reset Password (random password)
- Set Password (custom password)
If you don't define one or all of these variable the button for the undefined URLs will not be displayed.
If you don't define one or all of these variables, the button for the undefined URLs will not be displayed.
Most services will survive with the default template. If, however, you require extra buttons for whatever reason, you are free to provide your own template as long as you stick within the 4 columns. Multiple rows should be OK, though may be confusing to users.
Most services will survive with the default template. If, however, you require extra buttons for whatever reason, you are free to provide your own template as long as you stick within the 4 columns. Multiple rows should be OK, though it may be confusing to users.
### Menu Item Hook
If you services needs cannot be satisfied by the Service Control row, you are free to specify extra hooks by subclassing or instantiating the `services.hooks.MenuItemHook` class.
If your service needs cannot be satisfied by the Service Control row, you are free to specify extra hooks by subclassing or instantiating the `services.hooks.MenuItemHook` class.
For more information see the [Menu Hooks](menu-hooks.md) page.
For more information, see the [Menu Hooks](menu-hooks.md) page.
### The Service Manager
The service manager is what interacts with the external service. Ideally it should be completely agnostic about its environment, meaning that it should avoid calls to Alliance Auth and Django in general (except in special circumstances where the service is managed locally, e.g. Mumble). Data should come in already arranged by the Tasks and data passed back for the tasks to manage or distribute.
The service manager is what interacts with the external service. Ideally, it should be completely agnostic about its environment, meaning that it should avoid calls to Alliance Auth and Django in general (except in special circumstances where the service is managed locally, e.g., Mumble). Data should come in already arranged by the Tasks and data passed back for the tasks to manage or distribute.
The reason for maintaining this separation is that managers may be reused from other sources and there may not even be a need to write a custom manager. Likewise, by maintaining this neutral environment others may reuse the managers that we write. It can also significantly ease the unit testing of services.
The reason for maintaining this separation is that managers may be reused from other sources, and there may not even be a need to write a custom manager. Likewise, by maintaining this neutral environment, others may reuse the managers that we write. It can also significantly ease the unit testing of services.
### The Views
As mentioned at the start of this page, service modules are fully fledged Django apps. This means you're free to do whatever you wish with your views.
Typically most traditional username/password services define four views.
Typically, most traditional username/password services define four views.
- Create Account
- Delete Account
- Reset Password
- Set Password
These views should interact with the service via the Tasks, though in some instances may bypass the Tasks and access the manager directly where necessary, for example OAuth functionality.
These views should interact with the service via the Tasks, though in some instances may bypass the Tasks and access the manager directly where necessary, for example, OAuth functionality.
### The Tasks
The tasks component is the glue that holds all of the other components of the service module together. It provides the function implementation to handle things like adding and deleting users, updating groups, validating the existence of a users account. Whatever tasks `auth_hooks` and `views` have with interacting with the service will probably live here.
The tasks component is the glue that holds all the other components of the service module together. It provides the function implementation to handle things like adding and deleting users, updating groups, and validating the existence of a user's account. Whatever tasks `auth_hooks` and `views` have with interacting with the service will probably live here.
### The Models
Its very likely that you'll need to store data about a users remote service account locally. As service modules are fully fledged Django apps you are free to create as many models as necessary for persistent storage. You can create foreign keys to other models in Alliance Auth if necessary, though I _strongly_ recommend you limit this to the User and Groups models from `django.contrib.auth.models` and query any other data manually.
It's very likely that you'll need to store data about a users remote service account locally. As service modules are fully fledged Django apps, you are free to create as many models as necessary for persistent storage. You can create foreign keys to other models in Alliance Auth if necessary, though I _strongly_ recommend you limit this to the User and Groups models from `django.contrib.auth.models` and query any other data manually.
If you create models you should create the migrations that go along with these inside of your module/app.
If you create models, you should create the migrations that go along with them inside your module/app.
## Examples
There is a bare bones example service included in `services.modules.example`, you may like to use this as the base for your new service.
There is a bare-bones example service included in `services.modules.example`, you may like to use this as the base for your new service.
You should have a look through some of the other service modules before you get started to get an idea of the general structure of one. A lot of them aren't perfect so don't feel like you have to rigidly follow the structure of the existing services if you think its sub-optimal or doesn't suit the external service you're integrating.
You should have a look through some of the other service modules before you get started to get an idea of the general structure. A lot of them aren't perfect, so don't feel like you have to rigidly follow the structure of the existing services if you think its suboptimal or doesn't suit the external service you're integrating.
## Testing
You will need to add unit tests for all aspects of your service module before it is accepted. Be mindful that you don't actually want to make external calls to the service so you should mock the appropriate components to prevent this behavior.
You will need to add unit tests for all aspects of your service module before it is accepted. Be mindful that you don't actually want to make external calls to the service, so you should mock the appropriate components to prevent this behavior.
```{eval-rst}
.. autoclass:: allianceauth.services.hooks.ServicesHook

12
docs/development/custom/menu-hooks.md
View File

@ -1,8 +1,8 @@
# Menu Hooks
The menu hooks allow you to dynamically specify menu items from your plugin app or service. To achieve this you should subclass or instantiate the `services.hooks.MenuItemHook` class and then register the menu item with one of the hooks.
The menu hooks allow you to dynamically specify menu items from your plugin app or service. To achieve this, you should subclass or instantiate the `services.hooks.MenuItemHook` class and then register the menu item with one of the hooks.
To register a MenuItemHook class you would do the following:
To register a MenuItemHook class, you would do the following:
```python
@hooks.register('menu_item_hook')
@ -16,7 +16,7 @@ The `MenuItemHook` class specifies some parameters/instance variables required f
### text
The text shown as menu item, e.g. usually the name of the app.
The text shown as menu item, e.g., usually the name of the app.
### classes
@ -28,7 +28,7 @@ The name of the Django URL to use
### order
An integer which specifies the order of the menu item, lowest to highest. Community apps are free ot use an oder above `1000`. Numbers below are served for Auth.
An integer which specifies the order of the menu item, lowest to highest. Community apps are free ot use an oder above `1000`. The numbers below are reserved for Auth.
### navactive
@ -38,12 +38,12 @@ A list of views or namespaces the link should be highlighted on. See [django-nav
`count` is an integer shown next to the menu item as badge when `count` is not `None`.
This is a great feature to signal the user, that he has some open issues to take care of within an app. For example Auth uses this feature to show the specific number of open group request to the current user.
This is a great feature to signal the user that he has some open issues to take care of within an app. For example, Auth uses this feature to show the specific number of open group request to the current user.
:::{hint}
Here is how to stay consistent with the Auth design philosophy for using this feature:
1. Use it to display open items that the current user can close by himself only. Do not use it for items, that the user has no control over.
1. Use it to display open items that the current user can close by himself only. Do not use it for items that the user has no control over.
2. If there are currently no open items, do not show a badge at all.
:::
To use it set count the `render()` function of your subclass in accordance to the current user. Here is an example:

12
docs/development/custom/url-hooks.md
View File

@ -2,9 +2,9 @@
## Base functionality
The URL hooks allow you to dynamically specify URL patterns from your plugin app or service. To achieve this you should subclass or instantiate the `services.hooks.UrlHook` class and then register the URL patterns with the hook.
The URL hooks allow you to dynamically specify URL patterns from your plugin app or service. To achieve this, you should subclass or instantiate the `services.hooks.UrlHook` class and then register the URL patterns with the hook.
To register a UrlHook class you would do the following:
To register a UrlHook class, you would do the following:
```python
@hooks.register('url_hook')
@ -14,12 +14,12 @@ def register_urls():
### Public views
In addition is it possible to make views public. Normally, all views are automatically decorated with the `main_character_required` decorator. That decorator ensures a user needs to be logged in and have a main before he can access that view. This feature protects against a community app sneaking in a public view without the administrator knowing about it.
In addition, is it possible to make views public. Normally, all views are automatically decorated with the `main_character_required` decorator. That decorator ensures a user needs to be logged in and have a main before he can access that view. This feature protects against a community app sneaking in a public view without the administrator knowing about it.
An app can opt-out of this feature by adding a list of views to be excluded when registering the URLs. See the `excluded_views` parameter for details.
An app can opt out of this feature by adding a list of views to be excluded when registering the URLs. See the `excluded_views` parameter for details.
:::{note}
Note that for a public view to work, administrators need to also explicitly allow apps to have public views in their AA installation, by adding the apps label to ``APPS_WITH_PUBLIC_VIEWS`` setting.
Note that for a public view to work, administrators need to also explicitly allow apps to have public views in their AA installation, by adding the app label to ``APPS_WITH_PUBLIC_VIEWS`` setting.
:::
## Examples
@ -42,7 +42,7 @@ urlpatterns = [
]
```
Subsequently it would implement the UrlHook in a dedicated `auth_hooks.py` file like so:
Subsequently, it would implement the UrlHook in a dedicated `auth_hooks.py` file like so:
```python
from alliance_auth import hooks

94
docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md
View File

@ -1,20 +1,20 @@
# Development on Windows 10 with WSL and Visual Studio Code
This document describes step-by-step how to setup a complete development environment for Alliance Auth apps on Windows 10 with Windows Subsystem for Linux (WSL) and Visual Studio Code.
This document describes step-by-step how to set up a complete development environment for Alliance Auth apps on Windows 10 with Windows Subsystem for Linux (WSL) and Visual Studio Code.
The main benefit of this setup is that it runs all services and code in the native Linux environment (WSL) and at the same time can be full controlled from within a comfortable Windows IDE (Visual Studio Code) including code debugging.
The main benefit of this setup is that it runs all services and code in the native Linux environment (WSL) and at the same time can be fully controlled from within a comfortable Windows IDE (Visual Studio Code) including code debugging.
In addition all tools described in this guide are open source or free software.
In addition, all tools described in this guide are open source or free software.
:::{hint}
This guide is meant for development purposes only and not for installing AA in a production environment. For production installation please see chapter **Installation**.
This guide is meant for development purposes only and not for installing AA in a production environment. For production installation, please see chapter **Installation**.
:::
## Overview
The development environment consists of the following components:
- Visual Studio Code with Remote WSL and Python extension
- Visual Studio Code with the Remote WSL and Python extension
- WSL with Ubuntu (18.04. LTS or higher)
- Python environment on WSL (3.8 or higher)
- MySQL server on WSL
@ -22,15 +22,15 @@ The development environment consists of the following components:
- Alliance Auth on WSL
- Celery on WSL
We will use the build-in Django development web server, so we don't need to setup a WSGI server or a web server.
We will use the build-in Django development web server, so we don't need to set up a WSGI server or a web server.
:::{note}
This setup works with both WSL 1 and WSL 2. However, due to the significantly better performance we recommend WSL 2.
This setup works with both WSL 1 and WSL 2. However, due to the significantly better performance, we recommend WSL 2.
:::
## Requirement
The only requirement is a PC with Windows 10 and Internet connection in order to download the additional software components.
The only requirement is a PC with Windows 10 and Internet connection to download the additional software components.
## Installing Windows apps
@ -45,7 +45,7 @@ The only requirement is a PC with Windows 10 and Internet connection in order to
- Open the app and install the following VSC extensions:
- Remote WSL
- Connect to WSL. This will automatically install the VSC server on the VSC server for WSL
- Once connected to WSL install the Python extension on the WSL side
- Once connected to WSL, install the Python extension on the WSL side
## Setting up WSL / Linux
@ -64,13 +64,13 @@ sudo apt-get install gettext
### Install Python
Next we need to install Python and related development tools.
Next, we need to install Python and related development tools.
:::{note}
Should your Ubuntu come with a newer version of Python we recommend to still setup your dev environment with the oldest Python 3 version currently supported by AA (e.g Python 3.8 at this time of writing) to ensure your apps are compatible with all current AA installations
You an check out this `page <https://askubuntu.com/questions/682869/how-do-i-install-a-different-python-version-using-apt-get/1195153>`_ on how to install additional Python versions on Ubuntu.
Should your Ubuntu come with a newer version of Python we recommend to still set up your dev environment with the oldest Python 3 version currently supported by AA (e.g., Python 3.8 at this time of writing) to ensure your apps are compatible with all current AA installations
You can check out this `page <https://askubuntu.com/questions/682869/how-do-i-install-a-different-python-version-using-apt-get/1195153>`_ on how to install additional Python versions on Ubuntu.
If you install a different python version from the default you need to adjust some of the commands below to install appopriate versions of those packages for example using Python 3.8 you might need to run the following after using the setup steps for the repository mentioned in the AskUbuntu post above:
If you install a different python version from the default, you need to adjust some commands below to install appopriate versions of those packages, for example, using Python 3.8 you might need to run the following after using the setup steps for the repository mentioned in the AskUbuntu post above:
```shell
sudo apt-get install python3.8 python3.8-dev python3.8-venv python3-setuptools python3-pip python-pip
@ -108,7 +108,7 @@ sudo apt-get install mysql-server mysql-client libmysqlclient-dev
We chose to use MySQL instead of MariaDB, because the standard version of MariaDB that comes with this Ubuntu distribution will not work with AA.
:::
We need to apply a permission fix to mysql or you will get a warning with every startup:
We need to apply a permission fix to mysql, or you will get a warning with every startup:
```shell
sudo usermod -d /var/lib/mysql/ mysql
@ -120,7 +120,7 @@ Start the mysql server
sudo service mysql start
```
Create database and user for AA
Create a database and user for AA
```shell
sudo mysql -u root
@ -141,7 +141,7 @@ sudo mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql
```
:::{note}
If your WSL does not have an init.d service, it will not automatically start your services such as MySQL and Redis when you boot your Windows machine and you have to manually start them. For convenience we recommend putting these commands in a bash script. Here is an example:
If your WSL does not have an init.d service, it will not automatically start your services such as MySQL and Redis when you boot your Windows machine, and you have to manually start them. For convenience, we recommend putting these commands in a bash script. Here is an example:
```shell
#/bin/bash
@ -154,7 +154,7 @@ sudo redis-server --daemonize yes
### Setup dev folder on WSL
Setup your folders on WSL bash for your dev project. Our approach will setup one AA project with one venv and multiple apps running under the same AA project, but each in their own folder and git.
Set up your folders on WSL bash for your dev project. Our approach will set up one AA project with one venv and multiple apps running under the same AA project, but each in their own folder and git.
A good location for setting up this folder structure is your home folder or a subfolder of your home:
@ -167,7 +167,7 @@ A good location for setting up this folder structure is your home folder or a su
|- ...
```
Following this approach you can also setup additional AA projects, e.g. aa-dev-2, aa-dev-3 if needed.
Following this approach, you can also set up additional AA projects, e.g. aa-dev-2, aa-dev-3 if needed.
Create the root folder `aa-dev`.
@ -203,13 +203,13 @@ pip install -U pip setuptools wheel
pip install allianceauth
```
Now we are ready to setup our AA instance. Make sure to run this command in your aa-dev folder:
Now we are ready to set up our AA instance. Make sure to run this command in your aa-dev folder:
```shell
allianceauth start myauth
```
Next we will setup our VSC project for aa-dev by starting it directly from the WSL bash:
Next, we will set up our VSC project for aa-dev by starting it directly from the WSL bash:
```shell
code .
@ -217,11 +217,11 @@ code .
First you want to make sure exclude the venv folder from VSC as follows:
Open settings and go to Files:Exclude
Add pattern: `**/venv`
Add the pattern: `**/venv`
### Create EVE Online SSO App
For the Eve Online related setup you need to create a SSO app on the developer site:
For the Eve Online related setup you need to create an SSO app on the developer site:
- Create your Eve Online SSO App on the [Eve Online developer site](https://developers.eveonline.com/)
- Add all ESI scopes
@ -277,7 +277,7 @@ REGISTRATION_VERIFY_EMAIL = False
### Migrations and superuser
Before we can start AA we need to run migrations:
Before we can start AA, we need to run migrations:
```shell
cd myauth
@ -300,7 +300,7 @@ We are now ready to run out AA instance with the following command:
python manage.py runserver
```
Once running you can access your auth site on the browser under `http://localhost:8000`. Or the admin site under `http://localhost:8000/admin`
Once running, you can access your auth site on the browser under `http://localhost:8000`. Or the admin site under `http://localhost:8000/admin`
:::{hint}
You can start your AA server directly from a terminal window in VSC or with a VSC debug config (see chapter about debugging for details).
@ -308,14 +308,14 @@ You can start your AA server directly from a terminal window in VSC or with a VS
:::{note}
**Debug vs. Non-Debug mode**
Usually it is best to run your dev AA instance in debug mode, so you get all the detailed error messages that helps a lot for finding errors. But there might be cases where you want to test features that do not exist in debug mode (e.g. error pages) or just want to see how your app behaves in non-debug / production mode.
Usually it is best to run your dev AA instance in debug mode, so you get all the detailed error messages that help a lot for finding errors. But there might be cases where you want to test features that do not exist in debug mode (e.g. error pages) or just want to see how your app behaves in non-debug / production mode.
When you turn off debug mode you will see a problem though: Your pages will not render correctly. The reason is that Django will stop serving your static files in production mode and expect you to serve them from a real web server. Luckily, there is an option that forces Django to continue serving your static files directly even when not in debug mode. Just start your server with the following option: ``python manage.py runserver --insecure``
When you turn off debug mode, you will see a problem though: Your pages will not render correctly. The reason is that Django will stop serving your static files in production mode and expect you to serve them from a real web server. Luckily, there is an option that forces Django to continue serving your static files directly even when not in debug mode. Start your server with the following option: ``python manage.py runserver --insecure``
:::
### Celery
In addition you can start a celery worker instance for myauth. For development purposed it makes sense to only start one instance and add some additional logging.
In addition, you can start a celery worker instance for myauth. For development purposes, it makes sense to only start one instance and add some additional logging.
This can be done from the command line with the following command in the myauth folder (where manage.py is located):
@ -323,21 +323,21 @@ This can be done from the command line with the following command in the myauth
celery -A myauth worker -l info -P solo
```
Same as AA itself you can start Celery from any terminal session, from a terminal window within VSC or as a debug config in VSC (see chapter about debugging for details). For convenience we recommend starting Celery as debug config.
Same as AA itself, you can start Celery from any terminal session, from a terminal window within VSC or as a debug config in VSC (see chapter about debugging for details). For convenience, we recommend starting Celery as debug config.
## Debugging setup
To be able to debug your code you need to add debugging configuration to VSC. At least one for AA and one for celery.
To be able to debug your code, you need to add a debugging configuration to VSC. At least one for AA and one for celery.
### Breakpoints
By default VSC will break on any uncaught exception. Since every error raised by your tests will cause an uncaught exception we recommend to deactivate this feature.
By default, VSC will break on any uncaught exception. Since every error raised by your tests will cause an uncaught exception, we recommend deactivating this feature.
To deactivate open click on the debug icon to switch to the debug view. Then un-check "Uncaught Exceptions" on the breakpoints window.
To deactivate, click on the debug icon to switch to the debug view. Then uncheck "Uncaught Exceptions" in the "Breakpoints" window.
### AA debug config
In VSC click on Debug / Add Configuration and choose "Django". Should Django not appear as option make sure to first open a Django file (e.g. the local.py settings) to help VSC detect that you are using Django.
In VSC, click on Debug / Add Configuration and choose "Django". Should Django not appear as an option, make sure to first open a Django file (e.g., the local.py settings) to help VSC detect that you are using Django.
The result should look something like this:
@ -359,7 +359,7 @@ The result should look something like this:
### Debug celery
For celery we need another debug config, so that we can run it in parallel to our AA instance.
For celery, we need another debug config, so that we can run it in parallel to our AA instance.
Here is an example debug config for Celery:
@ -387,7 +387,7 @@ Here is an example debug config for Celery:
### Debug config for unit tests
Finally it makes sense to have a dedicated debug config for running unit tests. Here is an example config for running all tests of the app `example`.
Finally, it makes sense to have a dedicated debug config for running unit tests. Here is an example config for running all tests of the app `example`.
```json
{
@ -407,11 +407,11 @@ Finally it makes sense to have a dedicated debug config for running unit tests.
},
```
You can also specify to run just a part of your test suite down to a test method. Just give the full path to the test you want to run, e.g. `example.test.test_models.TestDemoModel.test_this_method`
You can also specify to run just a part of your test suite down to a test method. Give the full path to the test you want to run, e.g. `example.test.test_models.TestDemoModel.test_this_method`
### Debugging normal python scripts
Finally you may also want to have a debug config to debug a non-Django Python script:
Finally, you may also want to have a debug config to debug a non-Django Python script:
```json
{
@ -447,39 +447,37 @@ Extension for Visual Studio Code - Markdown linting and style checking for Visua
#### Live Server
Live Server allows you to start a mini webserver for any file quickly. This can e.g. be useful for looking at changes to to Sphinx docs.: [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer)
Live Server allows you to start a mini webserver for any file quickly. This can e.g. be useful for looking at changes to Sphinx docs.: [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer)
### Django apps
#### Django Extensions
[django-extensions](https://django-extensions.readthedocs.io/en/latest/) is a swiss army knife for django developers with adds a lot of very useful features to your Django site. Here are a few highlights:
[django-extensions](https://django-extensions.readthedocs.io/en/latest/) is a swiss army knife for django developers with adds a lot of useful features to your Django site. Here are a few highlights:
- shell_plus - An enhanced version of the Django shell. It will auto-load all your models at startup so you don't have to import anything and can use them right away.
- graph_models - Creates a dependency graph of Django models. Visualizing a model dependency structure can be very useful for trying to understand how an existing Django app works, or e.g. how all the AA models work together.
- runserver_plus - The standard runserver stuff but with the Werkzeug debugger baked in. This is a must have for any serious debugging.
- `shell_plus` - An enhanced version of the Django shell. It will autoload all your models at startup, so you don't have to import anything and can use them right away.
- `graph_models` - Creates a dependency graph of Django models. Visualizing a model dependency structure can be useful for trying to understand how an existing Django app works, or e.g., how all the AA models work together.
- `runserver_plus` - The standard runserver stuff but with the debugger baked in. This is a must-have for any serious debugging.
#### Django Debug Toolbar
The [Django Debug Toolbar](https://github.com/jazzband/django-debug-toolbar) is a configurable set of panels that display various debug information about the current request/response and when clicked, display more details about the panel's content.
E.g. this tool is invaluable to debug and fix performance issues with Django queries.
The [Django Debug Toolbar](https://github.com/jazzband/django-debug-toolbar) is a configurable set of panels that display various debug information about the current request/response and when clicked, display more details about the panel's content. This tool is invaluable to debug and fix performance issues with Django queries.
### Windows applications
#### DBeaver
DBeaver is a free universal database tool and works with many different kinds of databases include MySQL. It can be installed on Windows 10 and will be able to help manage your MySQL databases running on WSL.
DBeaver is a free universal database tool and works with many different kinds of databases including MySQL. It can be installed on Windows 10 and will be able to help manage your MySQL databases running on WSL.
Install from here. [DBeaver](https://dbeaver.io/)
## Adding apps for development
The idea behind the particular folder structure of aa-dev is to have each and every app in its own folder and git repo. To integrate them with the AA instance they need to be installed once using the -e option that enabled editing of the package. And then added to the INSTALLED_APPS settings.
The idea behind the particular folder structure of aa-dev is to have each and every app in its own folder and git repo. To integrate them with the AA instance, they need to be installed once using the -e option that enabled editing of the package. And then added to the INSTALLED_APPS settings.
To demonstrate let's add the example plugin to our environment.
To demonstrate, let's add the example plugin to our environment.
Open a WSL bash and navigate to the aa-dev folder. Make sure you have activate your virtual environment. (`source venv/bin/activate`)
Open a WSL bash and navigate to the aa-dev folder. Make sure you have activated your virtual environment. (`source venv/bin/activate`)
Run these commands:

2
docs/development/tech_docu/api/index.md
View File

@ -1,6 +1,6 @@
# API
To reduce redundancy and help speed up development we encourage developers to utilize the following packages when developing apps for Alliance Auth.
To reduce redundancy and help speed up development, we encourage developers to utilize the following packages when developing apps for Alliance Auth.
:::{toctree}
:maxdepth: 1

52
docs/development/tech_docu/celery.md
View File

@ -2,31 +2,31 @@
**Alliance Auth** uses Celery for asynchronous task management. This page aims to give developers some guidance on how to use Celery when developing apps for Alliance Auth.
For a complete documentation of Celery please refer to the [official Celery documentation](http://docs.celeryproject.org/en/latest/index.html).
For the complete documentation of Celery, please refer to the [official Celery documentation](http://docs.celeryproject.org/en/latest/index.html).
## When should I use Celery in my app?
There are two main cases for using celery. Long duration of a process and recurrence of a process.
There are two main reasons for using celery. Long duration of a process, and recurrence of a process.
### Duration
Alliance Auth is an online web application and as such the user expects fast and immediate responses to any of his clicks or actions. Same as with any other good web site. Good response times are measures in ms and a user will perceive everything that takes longer than 1 sec as an interruption of his flow of thought (see also [Response Times: The 3 Important Limits](https://www.nngroup.com/articles/response-times-3-important-limits/)).
Alliance Auth is an online web application, and as such, the user expects fast and immediate responses to any of his clicks or actions. Same as with any other good website. Good response times are measured in ms, and a user will perceive everything that takes longer than 1 sec as an interruption of his flow of thought (see also [Response Times: The 3 Important Limits](https://www.nngroup.com/articles/response-times-3-important-limits/)).
As a rule of thumb we therefore recommend to use celery tasks for every process that can take longer than 1 sec to complete (also think about how long your process might take with large amounts of data).
As a rule of thumb, we therefore recommend using celery tasks for every process that can take longer than 1 sec to complete (also think about how long your process might take with large amounts of data).
:::{note}
Another solution for dealing with long response time in particular when loading pages is to load parts of a page asynchronously, for example with AJAX.
Another solution for dealing with long response time in particular when loading pages is to load parts of a page asynchronously, for example, with AJAX.
:::
### Recurrence
Another case for using celery tasks is when you need recurring execution of tasks. For example you may want to update the list of characters in a corporation from ESI every hour.
Another case for using celery tasks is when you need recurring execution of tasks. For example, you may want to update the list of characters in a corporation from ESI every hour.
These are called periodic tasks and Alliance Auth uses [celery beat](https://docs.celeryproject.org/en/latest/userguide/periodic-tasks.html) to implement them.
These are called periodic tasks, and Alliance Auth uses [celery beat](https://docs.celeryproject.org/en/latest/userguide/periodic-tasks.html) to implement them.
## What is a celery task?
For the most part a celery task is a Python functions that is configured to be executed asynchronously and controlled by Celery. Celery tasks can be automatically retried, executed periodically, executed in work flows and much more. See the [celery docs](https://docs.celeryproject.org/en/latest/userguide/tasks.html) for a more detailed description.
For the most part, a celery task is a Python function configured to be executed asynchronously and controlled by Celery. Celery tasks can be automatically retried, executed periodically, executed in work flows and much more. See the [celery docs](https://docs.celeryproject.org/en/latest/userguide/tasks.html) for a more detailed description.
## How should I use Celery in my app?
@ -61,21 +61,21 @@ example.delay()
## How should I use celery tasks in the UI?
There is a well established pattern for integrating asynchronous processes in the UI, for example when the user asks your app to perform a longer running action:
There is a well-established pattern for integrating asynchronous processes in the UI, for example, when the user asks your app to perform a longer running action:
1. Notify the user immediately (with a Django message) that the process for completing the action has been started and that he will receive a report once completed.
2. Start the celery task
3. Once the celery task is completed it should send a notification containing the result of the action to the user. It's important to send that notification also in case of errors.
3. Once the celery task is completed, it should send a notification containing the result of the action to the user. It's important to send that notification also in case of errors.
## Can I use long running tasks?
## Can I use long-running tasks?
Long running tasks are possible, but in general Celery works best with short running tasks. Therefore we strongly recommend to try and break down long running tasks into smaller tasks if possible.
Long-running tasks are possible, but in general Celery works best with short running tasks. Therefore, we strongly recommend trying to break down long-running tasks into smaller tasks if possible.
If contextually possible try to break down your long running task in shorter tasks that can run in parallel.
If contextually possible, try to break down your long-running task in shorter tasks that can run in parallel.
However, many long running tasks consist of several smaller processes that need to run one after the other. For example you may have a loop where you perform the same action on hundreds of objects. In those cases you can define each of the smaller processes as it's own task and then link them together, so that they are run one after the other. That is called chaining in Celery and is the preferred approach for implementing long running processes.
However, many long-running tasks consist of several smaller processes that need to run one after the other. For example, you may have a loop where you perform the same action on hundreds of objects. In those cases, you can define each of the smaller processes as its own task and then link them together, so that they are run one after the other. That is called chaining in Celery and is the preferred approach for implementing long-running processes.
Example implementation for a celery chain:
@ -101,7 +101,7 @@ def long_runner():
chain(my_tasks).delay()
```
In this example we fist add 10 example tasks that need to run one after the other to a list. This can be done by creating a so called signature for a task. Those signature are a kind of wrapper for tasks and can be used in various ways to compose work flow for tasks.
In this example, we first add 10 example tasks that need to run one after the other to a list. This can be done by creating a so-called signature for a task. Those signatures are a kind of wrapper for tasks and can be used in various ways to compose work flow for tasks.
The list of task signatures is then converted to a chain and started asynchronously.
@ -110,12 +110,12 @@ In our example we use ``si()``, which is a shortcut for "immutable signatures" a
For more information on signature and work flows see the official documentation on `Canvas <https://docs.celeryproject.org/en/latest/userguide/canvas.html>`_.
In this context please note that Alliance Auth currently only supports chaining, because all other variants require a so called results back, which Alliance Auth does not have.
In this context, please note that Alliance Auth currently only supports chaining because all other variants require a so-called results back, which Alliance Auth does not have.
:::
## How can I define periodic tasks for my app?
Periodic tasks are normal celery tasks which are added the scheduler for periodic execution. The convention for defining periodic tasks for an app is to define them in the local settings. So user will need to add those settings manually to his local settings during the installation process.
Periodic tasks are normal celery tasks that are added to the scheduler for periodic execution. The convention for defining periodic tasks for an app is to define them in the local settings. So user will need to add those settings manually to his local settings during the installation process.
Example setting:
@ -126,14 +126,14 @@ CELERYBEAT_SCHEDULE['structures_update_all_structures'] = {
}
```
- `structures_update_all_structures` is the name of the scheduling entry. You can chose any name, but the convention is name of your app plus name of the task.
- `structures_update_all_structures` is the name of the scheduling entry. You can choose any name, but the convention is name of your app plus name of the task.
- `'task'`: Name of your task (full path)
- `'schedule'`: Schedule definition (see Celery documentation on [Periodic Tasks](https://docs.celeryproject.org/en/latest/userguide/periodic-tasks.html) for details)
## How can I use priorities for tasks?
In Alliance Auth we have defined task priorities from 0 - 9 as follows:
In Alliance Auth we have defined task priorities from 0 to 9 as follows:
```{eval-rst}
====== ========= ===========
@ -151,12 +151,12 @@ In Alliance Auth we have defined task priorities from 0 - 9 as follows:
:::{warning}
Please make sure to use task priorities with care and especially do not use higher priorities without a good reason. All apps including Alliance Auth share the same task queues, so using higher task priorities excessively can potentially prevent more important tasks (of other apps) from completing on time.
You also want to make sure to run use lower priorities if you have a large amount of tasks or long running tasks, which are not super urgent. (e.g. the regular update of all Eve characters from ESI runs with priority 7)
You also want to make sure to run use lower priorities if you have a large number of tasks or long-running tasks, which are not super urgent. (e.g., the regular update of all Eve characters from ESI runs with priority 7)
:::
:::{hint}
If no priority is specified all tasks will be started with the default priority, which is 5.
If no priority is specified, all tasks will be started with the default priority, which is 5.
:::
To run a task with a different priority you need to specify it when starting it.
To run a task with a different priority, you need to specify it when starting it.
Example for starting a task with priority 3:
@ -165,7 +165,7 @@ example.apply_async(priority=3)
```
:::{hint}
For defining a priority to tasks you can not use the convenient shortcut ``delay()``, but instead need to start a task with ``apply_async()``, which also requires you to pass parameters to your task function differently. Please check out the `official docs <https://docs.celeryproject.org/en/stable/reference/celery.app.task.html#celery.app.task.Task.apply_async>`_ for details.
For defining a priority to tasks, you cannot use the convenient shortcut ``delay()``, but instead need to start a task with ``apply_async()``, which also requires you to pass parameters to your task function differently. Please check out the `official docs <https://docs.celeryproject.org/en/stable/reference/celery.app.task.html#celery.app.task.Task.apply_async>`_ for details.
:::
## What special features should I be aware of?
@ -174,7 +174,7 @@ Every Alliance Auth installation will come with a couple of special celery relat
### celery-once
Celery-once is a celery extension "that allows you to prevent multiple execution and queuing of celery tasks". What that means is that you can ensure that only one instance of a celery task runs at any given time. This can be useful for example if you do not want multiple instances of you task to talk to the same external service at the same time.
Celery-once is a celery extension "that allows you to prevent multiple execution and queuing of celery tasks". What that means is that you can ensure that only one instance of a celery task runs at any given time. This can be useful, for example, if you do not want multiple instances of your task to talk to the same external service at the same time.
We use a custom backend for celery_once in Alliance Auth defined [here](https://gitlab.com/allianceauth/allianceauth/-/blob/master/allianceauth/services/tasks.py#L14)
You can import it for use like so:
@ -183,7 +183,7 @@ You can import it for use like so:
from allianceauth.services.tasks import QueueOnce
```
An example of AllianceAuth's use within the `@sharedtask` decorator, can be seen [here](https://gitlab.com/allianceauth/allianceauth/-/blob/master/allianceauth/services/modules/discord/tasks.py#L62) in the discord module
An example of Alliance Auth's use within the `@sharedtask` decorator, can be seen [here](https://gitlab.com/allianceauth/allianceauth/-/blob/master/allianceauth/services/modules/discord/tasks.py#L62) in the discord module
You can use it like so:
```python
@ -194,4 +194,4 @@ Please see the [official documentation](https://pypi.org/project/celery_once/) o
### task priorities
Alliance Auth is using task priorities to enable priority based scheduling of task execution. Please see [How can I use priorities for tasks?](#how-can-i-use-priorities-for-tasks) for details.
Alliance Auth is using task priorities to enable priority-based scheduling of task execution. Please see [How can I use priorities for tasks?](#how-can-i-use-priorities-for-tasks) for details.

2
docs/development/tech_docu/index.md
View File

@ -1,6 +1,6 @@
# Developing apps
In this section you find topics useful for app developers.
In this section, you find topics useful for app developers.
:::{toctree}
:maxdepth: 1

14
docs/features/apps/autogroups.md
View File

@ -1,6 +1,6 @@
# Auto Groups
Auto groups allows you to automatically place users of certain states into Corp or Alliance based groups. These groups are created when the first user is added to them and removed when the configuration is deleted.
Auto Groups allows you to automatically place users of certain states into corp or alliance-based groups. These groups are created when the first user is added to them and removed when the configuration is deleted.
## Installation
@ -10,19 +10,19 @@ To install this app add `'allianceauth.eveonline.autogroups',` to your `INSTALLE
## Configuring a group
When you create an autogroup config you will be given the following options:
When you create an autogroup config, you will be given the following options:
![Create Autogroup page](/_static/images/features/apps/autogroups/group-creation.png)
:::{warning}
After creating a group you wont be able to change the Corp and Alliance group prefixes, name source and the replace spaces settings. Make sure you configure these the way you want before creating the config. If you need to change these you will have to create a new autogroup config.
After creating a group, you won't be able to change the Corp and Alliance group prefixes, name source, and the replace spaces settings. Make sure you configure these the way you want before creating the config. If you need to change these, you will have to create a new autogroup config.
:::
- States selects which states will be added to automatic Corp/Alliance groups
- States select which states will be added to automatic Corp/Alliance groups
- Corp/Alliance groups checkbox toggles Corp/Alliance autogroups on or off for this config.
- Corp/Alliance group prefix sets the prefix for the group name, e.g. if your Corp was called `MyCorp` and your prefix was `Corp`, your autogroup name would be created as `Corp MyCorp`. This field accepts leading/trailing spaces.
- Corp/Alliance name source sets the source of the Corp/Alliance name used in creating the group name. Currently the options are Full name and Ticker.
- Replace spaces allows you to replace spaces in the autogroup name with the value in the Replace spaces with field. This can be blank.
- Corp/Alliance group prefix sets the prefix for the group name, e.g., if your corp was called `MyCorp` and your prefix was `Corp`, your autogroup name would be created as `Corp MyCorp`. This field accepts leading/trailing spaces.
- Corp/Alliance name source sets the source of the Corp/Alliance name used in creating the group name. Currently, the options are Full name and Ticker.
- Replace spaces allows you to replace spaces in the autogroup name with the value in the replace spaces with field. This can be blank.
## Permissions

22
docs/features/apps/corpstats.md
View File

@ -12,13 +12,13 @@ Add `'allianceauth.corputils',` to your `INSTALLED_APPS` list in your auth proje
## Creating a Corp Stats
Upon initial install, nothing will be visible. For every Corp, a model will have to be created before data can be viewed.
Upon initial installation, nothing will be visible. For every Corp, a model will have to be created before data can be viewed.
![nothing is visible](/_static/images/features/apps/corpstats/blank_header.png)
If you are a superuser, the add button will be immediate visible to you. If not, your user account requires the `add_corpstats` permission.
If you are a superuser, the "add" button will be immediately visible to you. If not, your user account requires the `add_corpstats` permission.
Corp Stats requires an EVE SSO token to access data from the EVE Swagger Interface. Upon pressing the Add button, you will be prompted to authenticated. Please select the character who is in the Corporation you want data for.
Corp Stats requires an EVE SSO token to access data from the EVE Swagger Interface. Upon pressing the Add button, you will be prompted to authenticate. Please select the character who is in the Corporation you want data for.
![authorize from the EVE site](/_static/images/features/apps/corpstats/eve_sso_authorization.png)
@ -26,8 +26,8 @@ You will return to auth where you are asked to select a token with the green arr
![select an SSO token to create with](/_static/images/features/apps/corpstats/select_sso_token.png)
If this works (and you have permission to view the Corp Stats you just created) you'll be returned to a view of the Corp Stats.
If it fails an error message will be displayed.
If this works (and you have permission to view the Corp Stats you just created), you'll be returned to a view of the Corp Stats.
If it fails, an error message will be displayed.
## Corp Stats View
@ -63,13 +63,13 @@ Each view contains a sortable and searchable table. The number of listings shown
![main list](/_static/images/features/apps/corpstats/main_list.png)
This list contains all main characters in registered in the selected Corporation and their alts. Each character has a link to [zKillboard](https://zkillboard.com).
This list contains all main characters registered in the selected Corporation and their alts. Each character has a link to [zKillboard](https://zkillboard.com).
#### Member List
![member list](/_static/images/features/apps/corpstats/member_list.png)
The list contains all characters in the Corporation. Red backgrounds means they are not registered in auth. A link to [zKillboard](https://zkillboard.com) is present for all characters.
The list contains all characters in the Corporation. Red backgrounds mean they are not registered in auth. A link to [zKillboard](https://zkillboard.com) is present for all characters.
If registered, the character will also have a main character, main Corporation, and main Alliance field.
#### Unregistered List
@ -108,7 +108,7 @@ Users who add a Corp Stats with their token will be granted permissions to view
## Automatic Updating
By default Corp Stats are only updated on demand. If you want to automatically refresh on a schedule, add an entry to your project's settings file:
By default, Corp Stats are only updated on demand. If you want to automatically refresh on a schedule, add an entry to your project's settings file:
```python
CELERYBEAT_SCHEDULE['update_all_corpstats'] = {
@ -134,11 +134,11 @@ Only one Corp Stats may exist at a time for a given Corporation.
>Failed to gather corporation statistics with selected token.
During initial population, the EVE Swagger Interface did not return any member data. This aborts the creation process. Please wait for the API to start working before attempting to create again.
During the initial population, the EVE Swagger Interface did not return any member data. This aborts the creation process. Please wait for the API to start working before attempting to create again.
### Failure to update Corp Stats
Any of the following errors will result in a notification to the owning user, and deletion of the Corp Stats model.
Any of the following errors will result in a notification to the owning user and deletion of the Corp Stats model.
>Your token has expired or is no longer valid. Please add a new one to create a new CorpStats.
@ -146,7 +146,7 @@ This occurs when the SSO token is invalid, which can occur when deleted by the u
>CorpStats for (corp name) cannot update with your ESI token as you have left corp.
The SSO token's character is no longer in the Corporation which the Corp Stats is for, and therefore membership data cannot be retrieved.
The SSO token's character is no longer in the Corporation that the Corp Stats are for, and therefore membership data cannot be retrieved.
>HTTPForbidden

24
docs/features/apps/hrapplications.md
View File

@ -4,7 +4,7 @@ This app allows you to manage applications for multiple corporations in your all
- Define application questionnaires for corporations
- Users can apply to corporations by filling outquestionnaires
- Manage review and approval process of applications
- Manage a review and approval process of applications
![hr](/_static/images/features/apps/hr.png)
@ -20,11 +20,11 @@ The most common task is creating ApplicationForm models for corps. Only when suc
The first step is to create questions. This is achieved by creating ApplicationQuestion models, one for each question. Titles are not unique.
Next step is to create the actual ApplicationForm model. It requires an existing EveCorporationInfo model to which it will belong. It also requires the selection of questions. ApplicationForm models are unique per Corporation: only one may exist for any given Corporation concurrently.
The next step is to create the actual ApplicationForm model. It requires an existing EveCorporationInfo model to which it will belong. It also requires the selection of questions. ApplicationForm models are unique per Corporation: only one may exist for any given Corporation concurrently.
You can adjust these questions at any time. This is the preferred method of modifying the form: deleting and recreating will cascade the deletion to all received applications from this form which is usually not intended.
You can adjust these questions at any time. This is the preferred method of modifying the form: deleting and recreating will cascade the deletion to all received applications from this form, which is usually not intended.
Once completed the Corporation will be available to receive applications.
Once completed, the Corporation will be available to receive applications.
### Reviewing Applications
@ -32,7 +32,7 @@ Superusers can see all applications, while normal members with the required perm
Selecting an application from the management screen will provide all the answers to the questions in the form at the time the user applied.
When a reviewer assigns themselves an application, they mark it as in progress. This notifies the applicant and permanently attached the reviewer to the application.
When a reviewer assigns themselves an application, they mark it as in progress. This notifies the applicant and permanently attaches the reviewer to the application.
Only the assigned reviewer can approve/reject/delete the application if they possess the appropriate permission.
@ -62,25 +62,25 @@ Users do not require any permission to apply to a corporation and fill out the f
A user with `auth.human_resources` can only see applications to their own corp.
Best practice is to bundle the `auth.human_resources` permission alongside the `hrapplications.approve_application` and `hrapplications.reject_application` permissions, as in isolation these don't make much sense.
Best practice is to bundle the `auth.human_resources` permission alongside the `hrapplications.approve_application` and `hrapplications.reject_application` permissions, as in isolation these make little sense.
## Models
### ApplicationQuestion
This is the model representation of a question. It contains a title, and a field for optional "helper" text. It is referenced by ApplicationForm models but acts independently. Modifying the question after it has been created will not void responses, so it's not advisable to edit the title or the answers may not make sense to reviewers.
This is the model representation of a question. It contains a title and a field for optional "helper" text. It is referenced by ApplicationForm models but acts independently. Modifying the question after it has been created will not void responses, so it's not advisable to edit the title or the answers may not make sense to reviewers.
### ApplicationForm
This is the template for an application. It points at a Corporation, with only one form allowed per Corporation. It also points at ApplicationQuestion models. When a user creates an application, they will be prompted with each question the form includes at the given time. Modifying questions in a form after it has been created will not be reflected in existing applications, so it's perfectly fine to adjust them as you see fit. Changing Corporations however is not advisable, as existing applications will point at the wrong Corporation after they've been submitted, confusing reviewers.
This is the template for an application. It points at a Corporation, with only one form allowed per Corporation. It also points at ApplicationQuestion models. When a user creates an application, they will be prompted with each question the form includes at the given time. Modifying questions in a form after it has been created will not be reflected in existing applications, so it's perfectly fine to adjust them as you see fit. Changing corporations, however, is not advisable, as existing applications will point at the wrong Corporation after they've been submitted, confusing reviewers.
### Application
This is the model representation of a completed application. It references an ApplicationForm from which it was spawned which is where the Corporation specificity comes from. It points at a user, contains info regarding its reviewer, and has a status. Shortcut properties also provide the applicant's main character, the applicant's APIs, and a string representation of the reviewer (for cases when the reviewer doesn't have a main character or the model gets deleted).
This is the model representation of a completed application. It references an ApplicationForm from which it was spawned, which is where the Corporation specificity comes from. It points at a user, contains info regarding its reviewer, and has a status. Shortcut properties also provide the applicant's main character, the applicant's APIs, and a string representation of the reviewer (for cases when the reviewer doesn't have a main character or the model gets deleted).
### ApplicationResponse
This is an answer to a question. It points at the Application to which it belongs, to the ApplicationQuestion which it is answering, and contains the answer text. Modifying any of these fields in dangerous.
This is an answer to a question. It points at the Application to which it belongs, to the ApplicationQuestion which it is answering, and contains the answer text. Modifying any of these fields is dangerous.
### ApplicationComment
@ -90,8 +90,8 @@ This is a reviewer's comment on an application. Points at the application, point
### No corps accepting applications
Ensure there are ApplicationForm models in the admin site. Ensure the user does not already have an application to these Corporations. If the users wishes to re-apply they must first delete their completed application
Ensure there are ApplicationForm models in the admin site. Ensure the user does not already have an application to these Corporations. If the users wish to re-apply, they must first delete their completed application
### Reviewer unable to complete application
Reviewers require a permission for each of the three possible outcomes of an application, Approve Reject or Delete. Any user with the human resources permission can mark an application as in-progress, but if they lack these permissions then the application will get stuck. Either grant the user the required permissions or change the assigned reviewer in the admin site. Best practice is to bundle the `auth.human_resources` permission alongside the `hrapplications.approve_application` and `hrapplications.reject_application` permissions, as in isolation these don't serve much purpose.
Reviewers require permission for each of the three possible outcomes of an application, Approve Reject or Delete. Any user with the human resources permission can mark an application as in-progress, but if they lack these permissions, then the application will get stuck. Either grant the user the required permissions or change the assigned reviewer in the admin site. Best practice is to bundle the `auth.human_resources` permission alongside the `hrapplications.approve_application` and `hrapplications.reject_application` permissions, as in isolation these serve little purpose.

2
docs/features/apps/index.md
View File

@ -1,6 +1,6 @@
# Apps
**Alliance Auth** comes with a set of apps (also called plugin-apps) which provide basic functions useful to many organizations in Eve Online like a fleet schedule and a timerboard. This section describes which apps are available and how to install and use them. Please note that any app need to be installed before it can be used.
**Alliance Auth** comes with a set of apps (also called plugin-apps) which provide basic functions useful to many organizations in Eve Online like a fleet schedule and a timerboard. This section describes which apps are available and how to install and use them. Please note that any app needs to be installed before it can be used.
:::{toctree}
:maxdepth: 1

6
docs/features/apps/permissions_tool.md
View File

@ -1,6 +1,6 @@
# Permissions Auditing
Access to most of Alliance Auth's features are controlled by Django's permissions system. In order to help you secure your services, Alliance Auth provides a permissions auditing tool.
Access to most of Alliance Auth's features is controlled by Django's permissions system. To help you secure your services, Alliance Auth provides a permission auditing tool.
This is an optional app that needs to be installed.
@ -10,9 +10,9 @@ To install it add `'allianceauth.permissions_tool',` to your `INSTALLED_APPS` li
### Access
In order to grant users access to the permissions auditing tool they will need to be granted the `permissions_tool.audit_permissions` permission or be a superuser.
To grant users access to the permission auditing tool, they will need to be granted the `permissions_tool.audit_permissions` permission or be a superuser.
When a user has access to the tool they will see the "Permissions Audit" menu item under the "Util" sub menu.
When a user has access to the tool, they will see the "Permissions Audit" menu item.
### Permissions Overview

4
docs/features/community/index.md
View File

@ -1,7 +1,7 @@
# Community Contributions
Another key feature of **Alliance Auth** is that it can be easily extended. Our great community is providing a variety of plug-in apps and services, which you can choose from to add more functions to your AA installation.
Another key feature of **Alliance Auth** is that it can be easily extended. Our great community is providing a variety of plug-in apps and services, which you can choose from to add more functions to your AA installation.
Check out the [Community Creations](https://gitlab.com/allianceauth/community-creations) repo for more details.
Or if you have specific needs you can of course always develop your own plugin- apps and services. Please see the [Development](/development/index.md) chapter for details.
Or if you have specific needs, you can always develop your own plugin-apps and services. Please see the [Development](/development/index.md) chapter for details.

28
docs/features/core/admin_site.md
View File

@ -1,26 +1,26 @@
# Admin Site
The admin site allows administrators to configure, manage and trouble shoot Alliance Auth and all it's applications and services. E.g. you can create new groups and assign groups to users.
The admin site allows administrators to configure, manage and troubleshoot Alliance Auth and all its applications and services. E.g., you can create new groups and assign groups to users.
You can open the admin site by clicking on "Admin" in the drop down menu for a user that has access.
You can open the admin site by clicking on "Admin" in the drop-down menu for a user that has access.
![Admin Site](/_static/images/features/core/admin_site.png)
## Setup for small to medium size installations
For small to medium size alliances it is often sufficient to have no more then two superuser admins (admins that also are superusers). Having two admins usually makes sense, so you can have one primary and one backup.
For small to medium size alliances, it is often sufficient to have no more than two superuser admins (admins that also are superusers). Having two admins usually makes sense, so you can have one primary and one backup.
:::{warning}
Superusers have read & write access to everything on your AA installation. Superusers also automatically have all permissions and therefore access to all features of your apps. Therefore we recommend to be very careful to whom you give superuser privileges.
Superusers have read & write access to everything on your AA installation. Superuser also automatically have all permissions and therefore access to all features of your apps. Therefore, we recommend to be very careful to whom you give superuser privileges.
:::
## Setup for large installations
For large alliances and coalitions you may want to have a couple of administrators to be able to distribute and handle the work load. However, having a larger number of superusers may be a security concern.
For large alliances and coalitions, you may want to have a couple of administrators to be able to distribute and handle the work load. However, having a larger number of superusers may be a security concern.
As an alternative to superusers admins you can define staff admins. Staff admins can perform most of the daily admin work, but are not superusers and therefore can be restricted in what they can access.
As an alternative to superusers admins, you can define staff admins. Staff admins can perform most of the daily admin work, but are not superusers and therefore can be restricted in what they can access.
To create a staff admin you need to do two things:
To create a staff admin, you need to do two things:
1. Enable the `is_staff` property for a user
1. Give the user permissions for admin tasks
@ -28,21 +28,21 @@ To create a staff admin you need to do two things:
:::{note}
Note that staff admins have the following limitations:
- Can not promote users to staff
- Can not promote users to superuser
- Can not add/remove permissions for users, groups and states
- Cannot promote users to staff
- Cannot promote users to superuser
- Cannot add/remove permissions for users, groups and states
These limitations exist to prevent staff admins to promote themselves to quasi superusers. Only superusers can perform these actions.
These limitations exist to prevent staff admins from promoting themselves to quasi superusers. Only superusers can perform these actions.
:::
### Staff property
Access to the admin site is restricted. Users needs to have the `is_staff` property to be able to open the site at all. The superuser that is created during the installation
Access to the admin site is restricted. Users need to have the `is_staff` property to be able to open the site at all. The superuser created during the installation
process will automatically have access to the admin site.
:::{hint}
Without any permissions a "staff user" can open the admin site, but can neither view nor edit anything except for viewing the list of permissions.
Without any permissions, a "staff user" can open the admin site, but can neither view nor edit anything except for viewing the list of permissions.
:::
### Permissions for common admin tasks
@ -91,4 +91,4 @@ Here is a list of permissions a staff admin would need to perform some common ad
### Permissions for other apps
The permissions a staff admin needs to perform tasks for other applications depends on how the applications are configured. the default is to have four permissions (change, delete, edit view) for each model of the applications. The view permission is usually required to see the model list on the admin site and the other three permissions are required to perform the respective action to an object of that model. However, app developer can chose to define permissions differently.
The permission a staff admin needs to perform tasks for other applications depends on how the applications are configured. The default is to have four permissions (change, delete, edit view) for each model of the applications. The view permission is usually required to see the model list on the admin site, and the other three permissions are required to perform the respective action to an object of that model. However, an app developer can choose to define permissions differently.

16
docs/features/core/analytics.md
View File

@ -6,7 +6,7 @@
Before you proceed, please read through this page and/or raise any concerns on the Alliance Auth discord. This data helps us make AA better.
To Opt-Out, modify our pre-loaded token using the Admin dashboard */admin/analytics/analyticstokens/1/change/
To opt out, modify our preloaded token using the Admin dashboard */admin/analytics/analyticstokens/1/change/
Each of the three features Daily Stats, Celery Events and Page Views can be enabled/Disabled independently.
@ -20,13 +20,13 @@ ANALYTICS_DISABLED = True
## What
Alliance Auth has taken great care to anonymize the data sent. In order to identify _unique_ installs we generate a UUIDv4, a random mathematical construct which does not contain any identifying information [UUID - UUID Objects](https://docs.python.org/3/library/uuid.html#uuid.uuid4)
Alliance Auth has taken great care to anonymize the data sent. To identify _unique_ installs, we generate a UUIDv4, a random mathematical construct which does not contain any identifying information [UUID - UUID Objects](https://docs.python.org/3/library/uuid.html#uuid.uuid4)
Analytics comes pre-loaded with our Google Analytics Token, and the Three Types of task can be opted out independently. Analytics can also be loaded with your _own_ GA token and the analytics module will act any/all tokens loaded.
Analytics comes preloaded with our Google Analytics token, and the three types of tasks can be opted out independently. Analytics can also be loaded with your _own_ GA token, and the analytics module will act any/all tokens loaded.
Our Daily Stats contain the following:
- A phone-in task to identify a servers existence
- A phone-in task to identify a server's existence
- A task to send the Number of User models
- A task to send the Number of Token Models
- A task to send the Number of Installed Apps
@ -36,7 +36,7 @@ Our Daily Stats contain the following:
Our Celery Events contain the following:
- Unique Identifier (The UUID)
- Celery Namespace of the task eg allianceauth.eveonline
- Celery Namespace of the task e.g., allianceauth.eveonline
- Celery Task
- Task Success or Exception
- A context number for bulk tasks or sometimes a binary True/False
@ -47,18 +47,18 @@ Our Page Views contain the following:
- Page Path
- Page Title
- The locale of the users browser
- The User-Agent of the users browser
- The User-Agent of the user's browser
- The Alliance Auth Version
## Why
This data allows Alliance Auth development to gather accurate statistics on our install base, as well as how those installs are used.
This data allows Alliance Auth development to gather accurate statistics on our installation base, as well as how those installations are used.
This allows us to better target our development time to commonly used modules and features and test them at the scales in use.
## Where
This data is stored in a Team Google Analytics Dashboard. The Maintainers all have Management permissions here, and if you have contributed to the Alliance Auth project or third party applications feel free to ask in the Alliance Auth discord for access.
This data is stored in a Team Google Analytics Dashboard. The Maintainers all have Management permissions here, and if you have contributed to the Alliance Auth project or third party applications, feel free to ask in the Alliance Auth discord for access.
## Using Analytics in my App

6
docs/features/core/dashboard.md
View File

@ -1,10 +1,10 @@
# Dashboard
The dashboard is the main page of the **Alliance Auth** website and the first page every logged in user will see.
The dashboard is the main page of the **Alliance Auth** website, and the first page every logged-in user will see.
The content of the dashboard is specific to the logged in user. It has a sidebar, which will display the list of apps a user currently as access to based on his permissions. And it also shows which character the user has registered and to which group he belongs.
The content of the dashboard is specific to the logged-in user. It has a sidebar, which will display the list of apps a user currently as access to based on his permissions. And it also shows which character the user has registered and to which group he belongs.
For admin users the dashboard shows additional technical information about the AA instance.
For admin users, the dashboard shows additional technical information about the AA instance.
![dashboard](/_static/images/features/core/dashboard/dashboard.png)

18
docs/features/core/groups.md
View File

@ -14,7 +14,7 @@ Here you have several options:
### Internal
Users cannot see, join or request to join this group. This is primarily used for Auth's internally managed groups, though can be useful if you want to prevent users from managing their membership of this group themselves. This option will override the Hidden, Open and Public options when enabled.
Users cannot see, join or request to join this group. This is primarily used for Auth's internally managed groups, though it can be useful if you want to prevent users from managing their membership of this group themselves. This option will override the Hidden, Open and Public options when enabled.
By default, every new group created will be an internal group.
@ -36,11 +36,11 @@ Group is accessible to any registered user, even when they do not have permissio
The key difference is that the group is completely unmanaged by Auth. **Once a member joins they will not be removed unless they leave manually, you remove them manually, or their account is deliberately set inactive or deleted.**
Most people won't have a use for public groups, though it can be useful if you wish to allow public access to some services. You can grant service permissions on a public group to allow this behavior.
Most people won't have a use for public groups, though it can be useful if you wish to allow public access to some services. You can grant service permissions to a public group to allow this behavior.
### Restricted
When a group is restricted only superuser admins can directly add or remove them to/from users. The purpose of this property is prevent staff admins from assigning themselves to groups that are security sensitive. The "restricted" property can be combined with all the other properties.
When a group is restricted, only superuser admins can directly add or remove them to/from users. The purpose of this property is to prevent staff admins from assigning themselves to groups that are security sensitive. The "restricted" property can be combined with all the other properties.
```{eval-rst}
.. _ref-reserved-group-names:
@ -48,15 +48,15 @@ When a group is restricted only superuser admins can directly add or remove them
## Reserved group names
When using Alliance Auth to manage external services like Discord, Auth will automatically duplicate groups on those services. E.g. on Discord Auth will create roles of the same name as groups. However, there may be cases where you want to manage groups on external services by yourself or by another bot. For those cases you can define a list of reserved group names. Auth will ensure that you can not create groups with a reserved name. You will find this list on the admin site under groupmanagement.
When using Alliance Auth to manage external services like Discord, Auth will automatically duplicate groups on those services. E.g., on Discord Auth will create roles of the same name as groups. However, there may be cases where you want to manage groups on external services by yourself or by another bot. For those cases, you can define a list of reserved group names. Auth will ensure that you cannot create groups with a reserved name. You will find this list on the admin site under groupmanagement.
:::{note}
While this feature can help to avoid naming conflicts with groups on external services, the respective service component in Alliance Auth also needs to be build in such a way that it knows how to prevent these conflicts. Currently only the Discord and Teamspeak3 services have this ability.
While this feature can help to avoid naming conflicts with groups on external services, the respective service component in Alliance Auth also needs to be built in such a way that it knows how to prevent these conflicts. Currently only the Discord and Teamspeak3 services have this ability.
:::
## Managing groups
In order to access group management, users need to be either a superuser, granted the `auth | user | group_management ( Access to add members to groups within the alliance )` permission or a group leader (discussed later).
To access group management, users need to be either a superuser, granted the `auth | user | group_management ( Access to add members to groups within the alliance )` permission or a group leader (discussed later).
### Group Requests
@ -64,7 +64,7 @@ When a user joins or leaves a group which is not marked as "Open", their group r
### Group Membership
The group membership tab gives an overview of all of the non-internal groups.
The group membership tab gives an overview of all the non-internal groups.
![Group overview](/_static/images/features/core/groupmanagement/group-membership.png)
@ -89,7 +89,7 @@ Group leaders have the same abilities as users with the `group_management` permi
- Approve requests for groups they are a leader of.
- View the Group Membership and Group Members of groups they are leaders of.
This allows you to more finely control who has access to manage which groups.
This allows you to more fine control who has access to manage which groups.
### Auto Leave
@ -121,7 +121,7 @@ Note that all settings are optional and the app will use the documented default
## Permissions
In order to join a group other than a public group, the permission `groupmanagement.request_groups` (`Can request non-public groups` in the admin panel) must be active on their account, either via a group or directly applied to their User account.
To join a group other than a public group, the permission `groupmanagement.request_groups` (`Can request non-public groups` in the admin panel) must be active on their account, either via a group or directly applied to their User account.
When a user loses this permission, they will be removed from all groups _except_ Public groups.

2
docs/features/core/index.md
View File

@ -1,6 +1,6 @@
# Core Features
Managing access to applications and services is one of the core functions of **Alliance Auth**. The related key concepts and functionalities are describes in this section.
Managing access to applications and services is one of the core functions of **Alliance Auth**. The related key concepts and functionalities are described in this section.
:::{toctree}
:maxdepth: 1

10
docs/features/core/notifications.md
View File

@ -1,14 +1,14 @@
# Notifications
Alliance Auth has a build in notification system. The purpose of the notification system is to provide an easy and quick way to send messages to users of Auth. For example some apps are using it to inform users about results after long running tasks have completed and admins will automatically get notifications about system errors.
Alliance Auth has a build in notification system. The purpose of the notification system is to provide an easy and quick way to send messages to users of Auth. For example, some apps are using it to inform users about results after long-running tasks have been completed, and admins will automatically get notifications about system errors.
The number of unread notifications is shown to the user in the top menu. And the user can click on the notification count to open the notifications app.
The number of unread notifications is shown to the user in the top menu. And the user can click on the notification count to open the Notifications app.
![notification app](/_static/images/features/core/notifications.png)
## Settings
The notifications app can be configured through settings.
The Notifications app can be configured through settings.
- `NOTIFICATIONS_REFRESH_TIME`: The unread count in the top menu is automatically refreshed to keep the user informed about new notifications. This setting allows to set the time between each refresh in seconds. You can also set it to `0` to turn off automatic refreshing. Default: `30`
- `NOTIFICATIONS_MAX_PER_USER`: Maximum number of notifications that are stored per user. Older notifications are replaced by newer once. Default: `50`
- `NOTIFICATIONS_REFRESH_TIME`: The unread count in the top menu is automatically refreshed to keep the user informed about new notifications. This setting allows setting the time between each refresh in seconds. You can also set it to `0` to turn off automatic refreshing. Default: `30`
- `NOTIFICATIONS_MAX_PER_USER`: Maximum number of notifications that are stored per user. Newer replace older notifications. Default: `50`

14
docs/features/core/states.md
View File

@ -1,10 +1,10 @@
# States
States define the basic role of a user based on his affiliation with your organization. A user that has a character in your organization (e.g. alliance) will usually have the `Member` state. And a user, that has no characters in your organization will usually have the `Guest` state.
States define the basic role of a user based on his affiliation with your organization. A user that has a character in your organization (e.g., alliance) will usually have the `Member` state. And a user, that has no characters in your organization will usually have the `Guest` state.
States are assigned and updated automatically. So a user which character just left your organization will automatically loose his `Member` state and get the `Guest` state instead.
States are assigned and updated automatically. So a user which character just left your organization will automatically lose his `Member` state and get the `Guest` state instead.
The main purpose of states like `Member` is to have one place where you can assign all permissions that should apply to all users with that particular state. For example if all your members should have access to the SRP app you would add the permission that gives access to the SRP app to the `Member` state.
The main purpose of states like `Member` is to have one place where you can assign all permissions that should apply to all users with that particular state. For example, if all your members should have access to the SRP app, you would add the permission that gives access to the SRP app to the `Member` state.
## Creating a State
@ -14,7 +14,7 @@ A number of fields are available and are described below.
### Name
This is the displayed name of a state. Should be self-explanatory.
This is the displayed name of a state. It should be self-explanatory.
### Permissions
@ -50,9 +50,9 @@ This lets you select which factions the state is available to. Factions can be a
States are mutually exclusive, meaning a user can only be in one at a time.
Membership is determined based on a user's main character. States are tested in order of descending priority - the first one which allows membership to the main character is assigned to the user.
Membership is determined based on a user's main character. States are tested in order of descending priority - the first one, which allows membership to the main character, is assigned to the user.
States are automatically assigned when a user registers to the site, their main character changes, they are activated or deactivated, or states are edited. Note that editing states triggers lots of state checks so it can be a very slow process.
States are automatically assigned when a user registers to the site, their main character changes, they are activated or deactivated, or states are edited. Note that editing states triggers lots of state checks, so it can be a very slow process.
Assigned states are visible in the `Users` section of the `Authentication` admin site.
@ -60,4 +60,4 @@ Assigned states are visible in the `Users` section of the `Authentication` admin
If no states are available to a user's main character, or their account has been deactivated, they are assigned to a catch-all `Guest` state. This state cannot be deleted nor can its name be changed.
The `Guest` state allows permissions to be granted to users who would otherwise not get any. For example access to public services can be granted by giving the `Guest` state a service access permission.
The `Guest` state allows permissions to be granted to users who would otherwise not get any. For example, access to public services can be granted by giving the `Guest` state a service access permission.

6
docs/features/overview.md
View File

@ -1,17 +1,17 @@
# Overview
**Alliance Auth** (AA) is a web site that helps Eve Online organizations efficiently manage access to applications and external services.
**Alliance Auth** (AA) is a website that helps Eve Online organizations efficiently manage access to applications and external services.
It has the following key features:
- Automatically grants or revokes users access to external services (e.g. Discord, Mumble) and web apps (e.g. SRP requests) based on the user's current membership to [in-game organizations](/features/core/states) and [groups](/features/core/groups)
- Provides a central web site where users can directly access web apps (e.g. SRP requests) and manage their access to external services and groups.
- Provides a central website where users can directly access web apps (e.g., SRP requests) and manage their access to external services and groups.
- Includes a set of connectors (called ["services"](/features/services/index)) for integrating access management with many popular external services like Discord, Mumble, Teamspeak 3, SMF and others
- Includes a set of web [apps](/features/apps/index) which add many useful functions, e.g.: fleet schedule, timer board, SRP request management, fleet activity tracker
- Can be easily extended with additional services and apps. Many are provided by the [community](/features/community/index).
- It can be easily extended with additional services and apps. Many are provided by the [community](/features/community/index).
- Chinese, English, German and Spanish localization

32
docs/features/services/discord.md
View File

@ -34,21 +34,21 @@ CELERYBEAT_SCHEDULE['discord.update_all_usernames'] = {
```
:::{note}
You will have to add most the values for these settings, e.g. your Discord server ID (aka guild ID), later in the setup process.
You will have to add most of the values for these settings, e.g., your Discord server ID (aka guild ID), later in the setup process.
:::
### Creating a Server
Navigate to the [Discord site](https://discord.com/) and register an account, or log in if you have one already.
On the left side of the screen you’ll see a circle with a plus sign. This is the button to create a new server. Go ahead and do that, naming it something obvious.
On the left side of the screen, you’ll see a circle with a plus sign. This is the button to create a new server. Go ahead and do that, naming it something obvious.
Now retrieve the server ID [following this procedure.](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-)
Update your auth project's settings file, inputting the server ID as `DISCORD_GUILD_ID`
:::{note}
If you already have a Discord server skip the creation step, but be sure to retrieve the server ID
If you already have a Discord server, skip the creation step, but be sure to retrieve the server ID
:::
### Registering an Application
@ -58,7 +58,7 @@ Give it a name and description relating to your auth site. Add a redirect to `ht
Update your auth project's settings file, inputting this redirect address as `DISCORD_CALLBACK_URL`
On the application summary page, press Create a Bot User.
On the application summary page, press "Create a Bot User".
Update your auth project's settings file with these pieces of information from the summary page:
@ -68,15 +68,15 @@ Update your auth project's settings file with these pieces of information from t
### Preparing Auth
Before continuing it is essential to run migrations and restart Gunicorn and Celery.
Before continuing, it is essential to run migrations and restart Gunicorn and Celery.
### Adding a Bot to the Server
Once created, navigate to the services page of your Alliance Auth install as the superuser account. At the top there is a big green button labelled Link Discord Server. Click it, then from the drop down select the server you created, and then Authorize.
Once created, navigate to the "Services" page of your Alliance Auth install as the superuser account. At the top there is a big green button labeled "Link Discord Server". Click it, then from the drop-down select the server you created, and then Authorize.
This adds a new user to your Discord server with a `BOT` tag, and a new role with the same name as your Discord application. Don't touch either of these. If for some reason the bot loses permissions or is removed from the server, click this button again.
To manage roles, this bot role must be at the top of the hierarchy. Edit your Discord server, roles, and click and drag the role with the same name as your application to the top of the list. This role must stay at the top of the list for the bot to work. Finally, the owner of the bot account must enable 2 Factor Authentication (this is required from Discord for kicking and modifying member roles). If you are unsure what 2FA is or how to set it up, refer to [this support page](https://support.discord.com/hc/en-us/articles/219576828). It is also recommended to force 2FA on your server (this forces any admins or moderators to have 2fa enabled to perform similar functions on discord).
To manage roles, this bot role must be at the top of the hierarchy. Edit your Discord server, roles, and click and drag the role with the same name as your application to the top of the list. This role must stay at the top of the list for the bot to work. Finally, the owner of the bot account must enable 2-Factor Authentication (this is required from Discord for kicking and modifying member roles). If you are unsure what 2FA is or how to set it up, refer to [this support page](https://support.discord.com/hc/en-us/articles/219576828). It is also recommended to force 2FA on your server (this forces any admins or moderators to have 2FA enabled to perform similar functions on discord).
Note that the bot will never appear online as it does not participate in chat channels.
@ -90,22 +90,22 @@ If you want users to have their Discord nickname changed to their in-game charac
## Managing Roles
Once users link their accounts you’ll notice Roles get populated on Discord. These are the equivalent to groups on every other service. The default permissions should be enough for members to use text and audio communications. Add more permissions to the roles as desired through the server management window.
Once users link their accounts, you’ll notice Roles get populated on Discord. These are the equivalent to groups on every other service. The default permissions should be enough for members to use text and audio communications. Add more permissions to the roles as desired through the server management window.
By default Alliance Auth is taking over full control of role assignments on Discord. This means that users on Discord can in general only have roles that correlate to groups on Auth. However, there are two exceptions to this rule.
By default, Alliance Auth is taking over full control of role assignments on Discord. This means that users in Discord can in general only have roles that correlate to groups on Auth. However, there are two exceptions to this rule.
### Internal Discord roles
First, users will keep their so called "Discord managed roles". Those are internal roles created by Discord e.g. for Nitro.
First, users will keep their so-called "Discord managed roles". Those are internal roles created by Discord, e.g., for Nitro.
### Excluding roles from being managed by Auth
Second, it is possible to exclude Discord roles from being managed by Auth at all. This can be useful if you have other bots on your Discord server that are using their own roles and which would otherwise conflict with Auth. This would also allow you to manage a role manually on Discord if you so chose.
To exclude roles from being managed by Auth you only have to add them to the list of reserved group names in Group Management.
To exclude roles from being managed by Auth, you only have to add them to the list of reserved group names in Group Management.
:::{note}
Role names on Discord are case sensitive, while reserved group names on Auth are not. Therefore reserved group names will cover all roles regardless of their case. For example if you have reserved the group name "alpha", then the Discord roles "alpha" and "Alpha" will both be persisted.
Role names on Discord are case-sensitive, while reserved group names on Auth are not. Therefore, reserved group names will cover all roles regardless of their case. For example, if you have reserved the group name "alpha", then the Discord roles "alpha" and "Alpha" will both be persisted.
:::
```{eval-rst}
@ -116,7 +116,7 @@ Role names on Discord are case sensitive, while reserved group names on Auth are
The Discord service contains a number of tasks that can be run to manually perform updates to all users.
You can run any of these tasks from the command line. Please make sure that you are in your venv and then you can run this command from the same folder that your manage.py is located:
You can run any of these tasks from the command line. Please make sure that you are in your venv, and then you can run this command from the same folder that your manage.py is located:
```shell
celery -A myauth call discord.update_all_groups
@ -175,8 +175,8 @@ This indicates your callback URL doesn't match. Ensure the `DISCORD_CALLBACK_URL
### "Add/Remove" Errors in Discord Service
If you are receiving errors in your Notifications after verifying that your settings are all correct try the following:
If you are receiving errors in your Notifications after verifying that your settings are all correct, try the following:
- Ensure that the bot's role in Discord is at the top of the roles list. Each time you add it to your server you will need to do this again.
- Make sure that the bot is not trying to modify the Owner of the discord, as it will fail. A holding discord account added with invite link will mitigate this.
- Ensure that the bot role in Discord is at the top of the roles list. Each time you add it to your server, you will need to do this again.
- Make sure that the bot is not trying to modify the Owner of the discord, as it will fail. A holding discord account added with an invite link will mitigate this.
- Make sure that the bot role on discord has all needed permissions, Admin etc., remembering that these will need to be set every time you add the bot to the Discord server.

8
docs/features/services/discourse.md
View File

@ -131,9 +131,9 @@ rake admin:create
Follow prompts, being sure to answer `y` when asked to allow admin privileges.
### Create API key
### Create an API key
Navigate to `discourse.example.com` and log on. Top right press the 3 lines and select `Admin`. Go to API tab and press `Generate Master API Key`.
Navigate to `discourse.example.com` and log on. Top right, press the 3 lines and select `Admin`. Go to API tab and press `Generate Master API Key`.
Add the following values to your auth project's settings file:
@ -149,9 +149,9 @@ Navigate to `discourse.example.com` and log in. Back to the admin site, scroll d
- `sso_url`: `http://example.com/discourse/sso`
- `sso_secret`: some secure key
Save, now set `DISCOURSE_SSO_SECRET` in your auth project's settings file to the secure key you just put in Discourse.
Now set `DISCOURSE_SSO_SECRET` in your auth project's settings file to the secure key you put in Discourse.
Finally run migrations and restart Gunicorn and Celery.
Finally, run migrations and restart Gunicorn and Celery.
## Permissions

44
docs/features/services/mumble.md
View File

@ -1,9 +1,9 @@
# Mumble
Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all the functionality and is easier to customize. And is better. I may be slightly biased.
Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all the functionality and is easier to customize. And it is better. I may be slightly biased.
:::{note}
Note that this guide assumes that you have installed Auth with the official :doc:`/installation/allianceauth` guide under ``/home/allianceserver`` and that it is called ``myauth``. Accordingly it assumes that you have a service user called ``allianceserver`` that is used to run all Auth services under supervisor.
Note that this guide assumes that you have installed Auth with the official :doc:`/installation/allianceauth` guide under ``/home/allianceserver`` and that it is called ``myauth``. Accordingly, it assumes that you have a service user called ``allianceserver`` that is used to run all Auth services under supervisor.
:::
:::{warning}
@ -50,7 +50,7 @@ We will now install the authenticator into your Auth virtual environment. Please
source /home/allianceserver/venv/auth/bin/activate
```
Install the python dependencies for the mumble authenticator. Note that this process can take 2-10 minutes to complete.
Install the python dependencies for the mumble authenticator. Note that this process can take 2 to 10 minutes to complete.
```shell
pip install -r requirements.txt
@ -58,7 +58,7 @@ pip install -r requirements.txt
## Configuring Mumble Server
The mumble server needs it's own database. Open an SQL shell with `mysql -u root -p` and execute the SQL commands to create it:
The mumble server needs its own database. Open an SQL shell with `mysql -u root -p` and execute the SQL commands to create it:
```sql
CREATE DATABASE alliance_mumble CHARACTER SET utf8mb4;
@ -68,7 +68,7 @@ CREATE DATABASE alliance_mumble CHARACTER SET utf8mb4;
GRANT ALL PRIVILEGES ON alliance_mumble . * TO 'allianceserver'@'localhost';
```
Mumble ships with a configuration file that needs customization. By default it’s located at `/etc/mumble-server.ini`. Open it with your favorite text editor:
Mumble ships with a configuration file that needs customization. By default, it’s located at `/etc/mumble-server.ini`. Open it with your favorite text editor:
```shell
sudo nano /etc/mumble-server.ini
@ -132,7 +132,7 @@ Test your configuration by starting it:
python /home/allianceserver/mumble-authenticator/authenticator.py
```
And finally ensure the allianceserver user has read/write permissions to the mumble authenticator files before proceeding:
And finally, ensure the allianceserver user has read/write permissions to the mumble authenticator files before proceeding:
```shell
sudo chown -R allianceserver:allianceserver /home/allianceserver/mumble-authenticator
@ -153,7 +153,7 @@ startsecs=10
priority=996
```
In addition we'd recommend to add the authenticator to Auth's restart group in your supervisor conf. For that you need to add it to the group line as shown in the following example:
In addition, we'd recommend adding the authenticator to Auth's restart group in your supervisor conf. For that, you need to add it to the group line as shown in the following example:
```ini
[group:myauth]
@ -161,7 +161,7 @@ programs=beat,worker,gunicorn,authenticator
priority=999
```
To enable the changes in your supervisor configuration you need to restart the supervisor process itself. And before we do that we are shutting down the current Auth supervisors gracefully:
To enable the changes in your supervisor configuration, you need to restart the supervisor process itself. And before we do that, we are shutting down the current Auth supervisors gracefully:
```shell
sudo supervisor stop myauth:
@ -225,28 +225,28 @@ The needs and available resources will vary between Alliance Auth installations.
### Bandwidth
<https://wiki.mumble.info/wiki/Murmur.ini#bandwidth>
This is likely the most important setting for scaling a Mumble install, The default maximum Bandwidth is 72000bps Per User. Reducing this value will cause your clients to automatically scale back their bandwidth transmitted, while causing a reduction in voice quality. A value thats still high may cause robotic voices or users with bad connections to drop due entirely due to network load.
This is likely the most important setting for scaling a Mumble installation, The default maximum Bandwidth is 72000bps Per User. Reducing this value will cause your clients to automatically scale back their bandwidth transmitted, while causing a reduction in voice quality. A value that's still high may cause robotic voices or users with bad connections to drop due entirely due to the network load.
Please tune this value to your individual needs, the below scale may provide a rough starting point.
72000 - Superior voice quality - Less than 50 users.
54000 - No noticeable reduction in quality - 50+ Users or many channels with active audio.
36000 - Mild reduction in quality - 100+ Users
30000 - Noticeable reduction in quality but not function - 250+ Users
`72000` - Superior voice quality - Less than 50 users.
`54000` - No noticeable reduction in quality - 50+ Users or many channels with active audio.
`36000` - Mild reduction in quality - 100+ Users
`30000` - Noticeable reduction in quality but not function - 250+ Users
### Forcing Opus
<https://wiki.mumble.info/wiki/Murmur.ini#opusthreshold>
A Mumble server by default, will fall back to the older CELT codec as soon as a single user connects with an old client. This will significantly reduce your audio quality and likely place higher load on your server. We _highly_ reccommend setting this to Zero, to force OPUS to be used at all times. Be aware any users with Mumble clients prior to 1.2.4 (From 2013...) Will not hear any audio.
A Mumble server, by default, will fall back to the older CELT codec as soon as a single user connects with an old client. This will significantly reduce your audio quality and likely place a higher load on your server. We _highly_ reccommend setting this to Zero, to force OPUS to be used at all times. Be aware any users with Mumble clients prior to 1.2.4 (From 2013...) Will not hear any audio.
`opusthreshold=0`
### AutoBan and Rate Limiting
<https://wiki.mumble.info/wiki/Murmur.ini#autobanAttempts.2C_autobanTimeframe_and_autobanTime>
The AutoBan feature has some sensible settings by default, You may wish to tune these if your users keep locking themselves out by opening two clients by mistake, or if you are receiving unwanted attention
The AutoBan feature has some sensible settings by default. You may wish to tune these if your users keep locking themselves out by opening two clients by mistake, or if you are receiving unwanted attention
<https://wiki.mumble.info/wiki/Murmur.ini#messagelimit_and_messageburst>
This too, is set to a sensible configuration by default. Take note on upgrading older installs, as this may actually be set too restrictively and will rate-limit your admins accidentally, take note of the configuration in <https://github.com/mumble-voip/mumble/blob/master/scripts/murmur.ini#L156>
This, too, is set to a sensible configuration by default. Take note on upgrading older installs, as this may actually be set too restrictively and will rate-limit your admins accidentally, take note of the configuration in <https://github.com/mumble-voip/mumble/blob/master/scripts/murmur.ini#L156>
### "Suggest" Options
@ -264,34 +264,34 @@ If Push to Talk is to your tastes, configure the suggestion as follows
### Setting a server password
With the default configuration your mumble server is public. Meaning that everyone who has the address can at least connect to it and might also be able join all channels that don't have any permissions set (Depending on your ACL configured for the root channel). If you want only registered member being able to join your mumble, you have to set a server password. To do so open your mumble server configuration which is by default located at `/etc/mumble-server.ini`.
With the default configuration, your mumble server is public. Meaning that everyone who has the address can at least connect to it and might also be able to join all channels that don't have any permissions set (Depending on your ACL configured for the root channel). If you want only registered member being able to join your mumble, you have to set a server password. To do so open your mumble server configuration which is by default located at `/etc/mumble-server.ini`.
```shell
sudo nano /etc/mumble-server.ini
```
Now search for `serverpassword=` and set your password here. If there is no such line, simply add it.
Now search for `serverpassword=` and set your password here. If there is no such line, add it.
```ini
serverpassword=YourSuperSecretServerPassword
```
Save the file and restart your mumble server afterwards.
Save the file and restart your mumble server afterward.
```shell
sudo service mumble-server restart
```
From now on, only registered member can join your mumble server. Now if you still want to allow guests to join you have 2 options.
From now on, only registered member can join your mumble server. Now if you still want to allow guests to join, you have two options.
- Allow the "Guest" state to activate the Mumble service in your Auth instance
- Use [Mumble temporary links](https://github.com/pvyParts/allianceauth-mumble-temp)
### Enabling Avatars in Overlay (V1.0.0+)
Ensure you have an up to date Mumble-Authenticator, this feature was added in V1.0.0
Ensure you have an up-to-date Mumble-Authenticator. This feature was added in V1.0.0
Edit `authenticator.ini` and change (or add for older installs) This code block.
Edit `authenticator.ini` and change (or add for older installations) This code block.
```ini
;If enabled, textures are automatically set as player's EvE avatar for use on overlay.

10
docs/features/services/nameformats.md
View File

@ -4,7 +4,7 @@ This app allows you to customize how usernames for services are created.
Each service's username or nickname, depending on which the service supports, can be customized through the use of the Name Formatter config provided the service supports custom formats. This config can be found in the admin panel under **Services -> Name format config**
Currently the following services support custom name formats:
Currently, the following services support custom name formats:
```{eval-rst}
+-------------+-----------+-------------------------------------+
@ -35,7 +35,7 @@ It's important to note here, before we get into what you can do with a name form
## Available format data
The following fields are available from a users account and main character:
The following fields are available for a user account and main character:
- `username` - Alliance Auth username
- `character_id`
@ -53,7 +53,7 @@ The following fields are available from a users account and main character:
The name formatter uses the advanced string formatting specified by [PEP-3101](https://www.python.org/dev/peps/pep-3101/). Anything supported by this specification is supported in a name formatter.
A more digestible documentation of string formatting in Python is available on the [PyFormat](https://pyformat.info/) website.
More digestible documentation of string formatting in Python is available on the [PyFormat](https://pyformat.info/) website.
Some examples of strings you could use:
@ -70,9 +70,9 @@ Some examples of strings you could use:
```
:::{important}
For most services, name formats only take effect when a user creates an account. This means if you create or update a name formatter it wont retroactively alter the format of users names. There are some exceptions to this where the service updates nicknames on a periodic basis. Check the service's documentation to see which of these apply.
For most services, name formats only take effect when a user creates an account. This means if you create or update a name formatter, it won't retroactively alter the format of users' names. There are some exceptions to this where the service updates nicknames on a periodic basis. Check the service's documentation to see which of these apply.
:::
:::{important}
You must only create one formatter per service per state. E.g. don't create two formatters for Mumble for the Member state. In this case one of the formatters will be used and it may not be the formatter you are expecting:
You must only create one formatter per service per state. E.g., don't create two formatters for Mumble for the Member state. In this case, one of the formatters will be used, and it may not be the formatter you are expecting:
:::

14
docs/features/services/openfire.md
View File

@ -58,11 +58,11 @@ sudo dnf install java-11-openjdk java-11-openjdk-devel
### Download Installer
Openfire is not available through repositories so we need to get a package from the developer.
Openfire is not available through repositories, so we need to get a package from the developer.
On your PC, navigate to the [Ignite Realtime downloads section](https://www.igniterealtime.org/downloads/index.jsp), and under Openfire select Linux, click on the Ubuntu: Debian package (second from bottom of list, ends with .deb) or CentOS: RPM Package (no JRE bundled, as we have installed it on the host)
On your PC, navigate to the [Ignite Realtime downloads section](https://www.igniterealtime.org/downloads/index.jsp), and under Openfire select Linux, click on the Ubuntu: Debian package (second from bottom of the list, ends with .deb) or CentOS: RPM Package (no JRE bundled, as we have installed it on the host)
Retrieve the file location by copying the URL from the “click here” link, depending on your browser you may have a Copy Link or similar option in your right click menu.
Retrieve the file location by copying the URL from the “click here” link. Depending on your browser, you may have a Copy Link or similar option in your right click menu.
In the console, ensure you’re in your user’s home directory:
@ -92,7 +92,7 @@ yum install -y openfire-4.7.2-1.noarch.rpm
### Create Database
Performance is best when working from a SQL database. If you installed MySQL or MariaDB alongside your auth project, go ahead and create a database for Openfire:
Performance is best when working from an SQL database. If you installed MySQL or MariaDB alongside your auth project, go ahead and create a database for Openfire:
```shell
mysql -u root -p
@ -128,11 +128,11 @@ Create an administrator account. The actual name is irrelevant, just don’t los
Finally, log in to the console with your admin account.
Edit your auth project's settings file and enter the values you just set:
Edit your auth project's settings file and enter the values you set:
- `JABBER_URL` is the pubic address of your jabber server
- `JABBER_URL` is the public address of your jabber server
- `JABBER_PORT` is the port for clients to connect to (usually 5223)
- `JABBER_SERVER` is the name of the jabber server. If you didn't alter it during install it'll usually be your domain (eg `example.com`)
- `JABBER_SERVER` is the name of the jabber server. If you didn't alter it during the installation, it'll usually be your domain (eg `example.com`)
- `OPENFIRE_ADDRESS` is the web address of Openfire's web interface. Use http:// with port 9090 or https:// with port 9091 if you configure SSL in Openfire
### REST API Setup

14
docs/features/services/permissions.md
View File

@ -4,17 +4,17 @@ In the past, access to services was dictated by a list of settings in `settings.
## Permissions based access
Instead of granting access to services by the previous rigid structure, access to services is now granted by the built in Django permissions system. This means that service access can be more granular, allowing only certain states, certain groups, for instance Corp CEOs, or even individual user access to each enabled service.
Instead of granting access to services by the previous rigid structure, access to services is now granted by the built-in Django permissions system. This means that service access can be more granular, allowing only certain states, certain groups, for instance, Corp CEOs, or even individual user access to each enabled service.
:::{important}
If you grant access to an individual user, they will have access to that service regardless of whether or not they are a member.
If you grant access to an individual user, they will have access to that service regardless of whether they are a member.
:::
Each service has an access permission defined, named like `Can access the <service name> service`.
To mimick the old behaviour of enabling services for all members, you would select the `Member` group from the admin panel, add the required service permission to the group and save. Likewise for Blues, select the `Blue` group and add the required permission.
To mimic the old behaviour of enabling services for all members, you would select the `Member` group from the admin panel, add the required service permission to the group and save. Likewise for Blues, select the `Blue` group and add the required permission.
A user can be granted the same permission from multiple sources. e.g. they may have it granted by several groups and directly granted on their account as well. Auth will not remove their account until all instances of the permission for that service have been revoked.
A user can be granted the same permission from multiple sources. e.g., they may have it granted by several groups and directly granted on their account as well. Auth will not remove their account until all instances of the permission for that service have been revoked.
## Removing access
@ -22,10 +22,10 @@ A user can be granted the same permission from multiple sources. e.g. they may h
Access removal is processed immediately after removing a permission from a user or group. If you remove access from a large group, such as Member, it will immediately remove all users from that service.
:::
When you remove a service permission from a user, a signal is triggered which will activate an immediate permission check. For users this will trigger an access check for all services. For groups, due to the potential extra load, only the services whose permissions have changed will be verified, and only the users in that group.
When you remove a service permission from a user, a signal is triggered which will activate an immediate permission check. For users, this will trigger an access check for all services. For groups, due to the potential extra load, only the services whose permissions have changed will be verified, and only the users in that group.
If a user no longer has permission to access the service when this permissions check is triggered, that service will be immediately disabled for them.
If a user no longer has permission to access the service when this permission check is triggered, that service will be immediately disabled for them.
### Disabling user accounts
When you unset a user as active in the admin panel, all of that users service accounts will be immediately disabled or removed. This is due to the built in behaviour of the Django permissions system, which will return False for all permissions if a users account is disabled, regardless of their actual permissions state.
When you unset a user as active in the admin panel, all of that user's service accounts will be immediately disabled or removed. This is due to the built-in behaviour of the Django permissions system, which will return False for all permissions if a user's account is disabled, regardless of their actual permissions state.

8
docs/features/services/phpbb3.md
View File

@ -67,7 +67,7 @@ Now we need to move this to our web directory. Usually `/var/www/forums`.
mv phpBB3 /var/www/forums
```
The web server needs read/write permission to this folder
The web server needs read/write permissions to this folder
Apache: `chown -R www-data:www-data /var/www/forums`
Nginx: `chown -R nginx:nginx /var/www/forums`
@ -80,7 +80,7 @@ Nginx: `chown -R nginx:nginx /var/www/forums`
### Configuring Web Server
You will need to configure you web server to serve PHPBB3 before proceeding with installation.
You will need to configure your web server to serve PHPBB3 before proceeding with installation.
A minimal Apache config file might look like:
@ -128,7 +128,7 @@ Enter your forum's web address as the `PHPBB3_URL` setting in your auth project'
### Web Install
Navigate to your forums web address where you will be presented with an installer.
Navigate to your forum web address where you will be presented with an installer.
Click on the `Install` tab.
@ -155,7 +155,7 @@ phpBB will then write its own config file.
### Open the Forums
Before users can see the forums, we need to remove the install directory
Before users can see the forums, we need to remove the installation directory
```shell
rm -rf /var/www/forums/install

8
docs/features/services/smf.md
View File

@ -32,7 +32,7 @@ DATABASES['smf'] = {
### Download SMF
Using your browser, you can download the latest version of SMF to your desktop computer. All SMF downloads can be found at SMF Downloads. The latest recommended version will always be available at <http://www.simplemachines.org/download/index.php/latest/install/>. Retrieve the file location from the hyperlinked box icon for the zip full install, depending on your browser you may have a Copy Link or similar option in your right click menu.
Using your browser, you can download the latest version of SMF to your desktop computer. All SMF downloads can be found at SMF Downloads. The latest recommended version will always be available at <http://www.simplemachines.org/download/index.php/latest/install/>. Retrieve the file location from the hyperlinked box icon for the zip full install, depending on your browser, you may have a Copy Link or similar option in your right click menu.
Download using wget, replacing the URL with the URL for the package you just retrieved
@ -52,13 +52,13 @@ Now we need to move this to our web directory. Usually `/var/www/forums`.
mv smf /var/www/forums
```
The web server needs read/write permission to this folder
The web server needs read/write permissions to this folder
Apache: `chown -R www-data:www-data /var/www/forums`
Nginx: `chown -R nginx:nginx /var/www/forums`
:::{tip}
Nginx: Some distributions use the ``www-data:www-data`` user:group instead of ``nginx:nginx``. If you run into problems with permissions try it instead.
Nginx: Some distributions use the ``www-data:www-data`` user:group instead of ``nginx:nginx``. If you run into problems with permissions, try it instead.
:::
### Database Preparation
@ -117,7 +117,7 @@ Enter the web address to your forums into the `SMF_URL` setting in your auth pro
### Web Install
Navigate to your forums address where you will be presented with an installer.
Navigate to your forum address where you will be presented with an installer.
Click on the `Install` tab.

12
docs/features/services/teamspeak3.md
View File

@ -34,7 +34,7 @@ CELERYBEAT_SCHEDULE['run_ts3_group_update'] = {
### Download Installer
To install we need a copy of the server. You can find the latest version from the [TeamSpeak site](https://www.teamspeak.com/downloads#)). Be sure to get a link to the Linux version.
To install, we need a copy of the server. You can find the latest version on the [TeamSpeak website](https://www.teamspeak.com/downloads#). Be sure to get a link to the Linux version.
Download the server, replacing the link with the link you got earlier.
@ -75,7 +75,7 @@ ln -s /usr/local/teamspeak/ts3server_startscript.sh /etc/init.d/teamspeak
update-rc.d teamspeak defaults
```
Finally we start the server.
Finally, we start the server.
```shell
service teamspeak start
@ -109,7 +109,7 @@ Click the URL provided to automatically connect to our server. It will prompt yo
### Groups
Now we need to make groups. AllianceAuth handles groups in teamspeak differently: instead of creating groups it creates an association between groups in TeamSpeak and groups in AllianceAuth. Go ahead and make the groups you want to associate with auth groups, keeping in mind multiple TeamSpeak groups can be associated with a single auth group.
Now we need to make groups. AllianceAuth handles groups in teamspeak differently: instead of creating groups, it creates an association between groups in TeamSpeak and groups in AllianceAuth. Go ahead and make the groups you want to associate with auth groups, keeping in mind multiple TeamSpeak groups can be associated with a single auth group.
Navigate back to the AllianceAuth admin interface (example.com/admin) and under `Teamspeak3`, select `Auth / TS Groups`.
@ -127,7 +127,7 @@ To enable advanced permissions, on your client go to the `Tools` menu, `Applicat
### TS group models not populating on admin site
The method which populates these runs every 30 minutes. To populate manually you start the process from the admin site or from the Django shell.
The method which populates these runs every 30 minutes. To populate manually, you start the process from the admin site or from the Django shell.
#### Admin Site
@ -156,7 +156,7 @@ Ensure that command does not return an error.
This usually occurs because auth is trying to remove a user from the `Guest` group (group ID 8). The guest group is only assigned to a user when they have no other groups, unless you have changed the default teamspeak server config.
Teamspeak servers v3.0.13 and up are especially susceptible to this. Ensure the Channel Admin Group is not set to `Guest (8)`. Check by right clicking on the server name, `Edit virtual server`, and in the middle of the panel select the `Misc` tab.
Teamspeak servers v3.0.13 and up are especially susceptible to this. Ensure the Channel Admin Group is not set to `Guest (8)`. Check by right-clicking on the server name, `Edit virtual server`, and in the middle of the panel select the `Misc` tab.
### `TypeError: string indices must be integers, not str`
@ -174,7 +174,7 @@ The serverquery account login specified in local.py is incorrect. Please verify
### `2568 insufficient client permissions`
This usually occurs if you've created a separate serverquery user to use with auth. It has not been assigned sufficient permissions to complete all the tasks required of it. The full list of required permissions is not known, so assign liberally.
This usually occurs if you've created a separate serverquery user to use with auth. It has not been assigned sufficient permissions to complete all the tasks required of it. The full list of required permissions is not known, so assign them liberally.
## Permissions

8
docs/features/services/xenforo.md
View File

@ -2,7 +2,7 @@
## Overview
[XenForo](https://xenforo.com/) is a popular paid forum. This guide will assume that you already have XenForo installed with a valid license (please keep in mind that XenForo is not free nor open-source, therefore you need to purchase a license first). If you come across any problems related with the installation of XenForo please contact their support service.
[XenForo](https://xenforo.com/) is a popular, paid forum. This guide will assume that you already have XenForo installed with a valid license (please keep in mind that XenForo is not free nor open-source, therefore, you need to purchase a license first). If you come across any problems related with the installation of XenForo please contact their support service.
## Prepare Your Settings
@ -20,12 +20,12 @@ XENFORO_APIKEY = 'yourapikey'
## XenAPI
By default XenForo does not support any kind of API, however there is a third-party package called [XenAPI](https://github.com/Contex/XenAPI) which provides a simple REST interface by which we can access XenForo's functions in order to create and edit users.
By default, XenForo does not support any kind of API, however, there is a third-party package called [XenAPI](https://github.com/Contex/XenAPI) which provides a simple REST interface by which we can access XenForo's functions to create and edit users.
The installation of XenAPI is pretty straight forward. The only thing you need to do is to download the `api.php` from the official repository and upload it in the root folder of your XenForo installation. The final result should look like this:
*forumswebsite.com/***api.php**
Now that XenAPI is installed the only thing left to do is to provide a key.
Now that XenAPI is installed, the only thing left to do is to provide a key.
```php
$restAPI = new RestAPI('REPLACE_THIS_WITH_AN_API_KEY');
@ -37,7 +37,7 @@ The settings you created earlier now need to be filled out.
`XENFORO_ENDPOINT` is the address to the API you added. No leading `http://`, but be sure to include the `/api.php` at the end.
`XENFORO_DEFAULT_GROUP` is the ID of the group in XenForo auth users will be added to. Unfortunately XenAPI **cannot create new groups**, therefore you have to create a group manually and then get its ID.
`XENFORO_DEFAULT_GROUP` is the ID of the group in XenForo auth users will be added to. Unfortunately, XenAPI **cannot create new groups**, therefore, you have to create a group manually and then get its ID.
`XENFORO_API_KEY` is the API key value you set earlier.

28
docs/installation/allianceauth.md
View File

@ -24,7 +24,7 @@ To install on your favorite flavour of Linux, identify and install equivalent pa
### OS Maintenance
It is recommended to ensure your OS is fully up to date before proceeding. We may also add Package Repositories here, used later in the documentation.
It is recommended to ensure your OS is fully up-to-date before proceeding. We may also add Package Repositories here, used later in the documentation.
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
@ -319,7 +319,7 @@ sudo chown -R allianceserver:allianceserver /var/www/myauth/static/
```
:::{warning}
When installing and performing maintenance on Alliance Auth, virtual environments and python packages, _sudo_ means _superuser_ _do_, this will not use your venv or your allianceserver user and will routinely break your permission structure.
When installing and performing maintenance on Alliance Auth, virtual environments and python packages, _sudo_ means _superuser_ _do_, this will not use your venv or your allianceserver user and will routinely break your permission structure.
Only use sudo for _system_ management or if you are unsure, when explicitly instructed to do so.
@ -337,7 +337,7 @@ Switch to the allianceserver user.
sudo su allianceserver
```
And switch to it's home directory:
And switch to its home directory:
```shell
cd ~
@ -371,14 +371,14 @@ Each time you come to do maintenance on your Alliance Auth installation, you sho
You need to have a dedicated Eve SSO app for Alliance auth. Please go to [EVE Developer](https://developers.eveonline.com/applications) to create one.
For **scopes** your SSO app needs to have at least `publicData`. Additional scopes depends on which Alliance Auth apps you will be using. For convenience, we recommend adding all available ESO scopes to your SSO app. Note that Alliance Auth will always ask the users to approve specific scopes before they are used.
For **scopes** your SSO app needs to have at least `publicData`. Additional scopes depend on which Alliance Auth apps you will be using. For convenience, we recommend adding all available ESO scopes to your SSO app. Note that Alliance Auth will always ask the users to approve specific scopes before they are used.
As **callback URL** you want to define the URL of your Alliance Auth site plus the route: `/sso/callback`. Example for a valid callback URL: `https://auth.example.com/sso/callback`
### Alliance Auth Project
:::{warning}
Before installing any Python packages please double-check that you have activated in the virtual environment. This is usually indicated by your command line in the terminal starting with: `(auth)`.
Before installing any Python packages, please double-check that you have activated in the virtual environment. This is usually indicated by your command line in the terminal starting with: `(auth)`.
:::
#### Install Python packages
@ -395,7 +395,7 @@ You can install **Alliance Auth** with the following command. This will install
pip install allianceauth superlance gunicorn
```
#### Create Alliance Auth project
#### Create the Alliance Auth project
Now you need to create the Django project that will run **Alliance Auth**. Ensure you are in the allianceserver home directory by issuing:
@ -427,7 +427,7 @@ nano myauth/myauth/settings/local.py
#### Install database & static files
Django needs to setup the database before it can start.
Django needs to set up the database before it can start.
```shell
python /home/allianceserver/myauth/manage.py migrate
@ -462,9 +462,9 @@ Before using your auth site, it is essential to create a superuser account. This
python /home/allianceserver/myauth/manage.py createsuperuser
```
Once your install is complete, the superuser account is accessed by logging in via the admin site at `https://example.com/admin`.
Once your installation is complete, the superuser account is accessed by logging in via the admin site at `https://example.com/admin`.
If you intend to use this account as your personal auth account you need to add a main character. Navigate to the normal user dashboard (at `https://example.com`) after logging in via the admin site and select `Change Main`. Once a main character has been added, it is possible to use SSO to login to this account.
If you intend to use this account as your personal auth account, you need to add a main character. Navigate to the normal user dashboard (at `https://example.com`) after logging in via the admin site and select `Change Main`. Once a main character has been added, it is possible to use SSO to log in to this account.
## Services
@ -472,7 +472,7 @@ Alliance Auth needs some additional services to run, which we will set up and co
### Gunicorn
To run the **Alliance Auth** website a [WSGI Server](https://www.fullstackpython.com/wsgi-servers.html) is required. For this [Gunicorn](http://gunicorn.org/) is highly recommended for its ease of configuring. It can be manually run from within your `myauth` base directory with `gunicorn --bind 0.0.0.0 myauth.wsgi` or automatically run using Supervisor.
To run the **Alliance Auth** website, a [WSGI Server](https://www.fullstackpython.com/wsgi-servers.html) is required. For this [Gunicorn](http://gunicorn.org/) is highly recommended for its ease of configuring. It can be manually run from within your `myauth` base directory with `gunicorn --bind 0.0.0.0 myauth.wsgi` or automatically run using Supervisor.
If you don't see any errors, this means that Gunicorn is running fine. You can stop it with `Ctrl+C` now.
@ -585,7 +585,7 @@ Activate it with `sudo supervisorctl reload`.
You can check the status of the processes with `sudo supervisorctl status`. Logs from these processes are available in `/home/allianceserver/myauth/log` named by process.
:::{note}
Any time the code or your settings change you'll need to restart Gunicorn and Celery. ::
Any time the code or your settings change, you'll need to restart Gunicorn and Celery. ::
```shell
sudo supervisorctl restart myauth:
@ -597,13 +597,13 @@ sudo supervisorctl restart myauth:
Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md) and follow the respective guide.
Note that Alliance Auth is designed to run with web servers on HTTPS. While running on HTTP is technically possible, it is not recommended for production use, and some functions (e.g. Email confirmation links) will not work properly.
Note that Alliance Auth is designed to run with web servers on HTTPS. While running on HTTP is technically possible, it is not recommended for production use, and some functions (e.g., Email confirmation links) will not work properly.
## Updating
Periodically [new releases](https://gitlab.com/allianceauth/allianceauth/tags) are issued with bug fixes and new features. Be sure to read the [release notes](https://gitlab.com/allianceauth/allianceauth/-/releases) which will highlight changes.
To update your install, swap to your allianceserver user
To update your installation, swap to your allianceserver user
```shell
sudo su allianceserver
@ -633,7 +633,7 @@ Some releases come with new or changed models. Update your database to reflect t
python /home/allianceserver/myauth/manage.py migrate
```
Finally, some releases come with new or changed static files. Run the following command to update your static files folder:
Finally, some releases come with new or changed static files. Run the following command to update your static files' folder:
```shell
python /home/allianceserver/myauth/manage.py collectstatic --noinput

8
docs/installation/apache.md
View File

@ -2,7 +2,7 @@
## Overview
Alliance Auth gets served using a Web Server Gateway Interface (WSGI) script. This script passes web requests to Alliance Auth which generates the content to be displayed and returns it. This means very little has to be configured in Apache to host Alliance Auth.
Alliance Auth gets served using a Web Server Gateway Interface (WSGI) script. This script passes web requests to Alliance Auth, which generates the content to be displayed and returns it. This means very little has to be configured in Apache to host Alliance Auth.
If you're using a small VPS to host services with very limited memory, consider using [NGINX](nginx.md).
@ -78,7 +78,7 @@ chown -R apache:apache /var/www/myauth/static
Apache serves sites through defined virtual hosts. These are located in `/etc/apache2/sites-available/` on Ubuntu and `/etc/httpd/conf.d/httpd.conf` on CentOS.
A virtual host for auth need only proxy requests to your WSGI server (Gunicorn if you followed the install guide) and serve static files. Examples can be found below. Create your config in its own file e.g. `myauth.conf`
A virtual host for auth needs only proxy requests to your WSGI server (Gunicorn if you followed the installation guide) and serve static files. Examples can be found below. Create your config in its own file e.g. `myauth.conf`
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
@ -152,7 +152,7 @@ a2dissite 000-default.conf
It's 2018 - there's no reason to run a site without SSL. The EFF provides free, renewable SSL certificates with an automated installer. Visit their [website](https://certbot.eff.org/) for information.
After acquiring SSL the config file needs to be adjusted. Add the following lines inside the `<VirtualHost>` block:
After acquiring SSL, the config file needs to be adjusted. Add the following lines inside the `<VirtualHost>` block:
```ini
RequestHeader set X-FORWARDED-PROTOCOL https
@ -163,7 +163,7 @@ After acquiring SSL the config file needs to be adjusted. Add the following line
#### Apache2 vs. Django
For some versions of Apache2 you might have to tell the Django framework explicitly
For some versions of Apache2, you might have to tell the Django framework explicitly
to use SSL, since the automatic detection doesn't work. SSL in general will work,
but internally created URLs by Django might still be prefixed with just `http://`
instead of `https://`, so it can't hurt to add these lines to

18
docs/installation/gunicorn.md
View File

@ -2,12 +2,12 @@
[Gunicorn](http://gunicorn.org) is a Python WSGI HTTP Server for UNIX. The Gunicorn server is light on server resources, and fairly speedy.
If you find Apache's `mod_wsgi` to be a headache or want to use NGINX (or some other webserver), then Gunicorn could be for you. There are a number of other WSGI server options out there and this documentation should be enough for you to piece together how to get them working with your environment.
If you find Apache's `mod_wsgi` to be a headache or want to use NGINX (or some other webserver), then Gunicorn could be for you. There are a number of other WSGI server options out there, and this documentation should be enough for you to piece together how to get them working with your environment.
Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html).
:::{note}
The page contains additional steps on how to setup and configure Gunicorn that are not required for users who decide to stick with the default Gunicorn configuration as described in the main installation guide for AA.
The page contains additional steps on how to set up and configure Gunicorn that are not required for users who decide to stick with the default Gunicorn configuration as described in the main installation guide for AA.
:::
## Setting up Gunicorn
@ -30,7 +30,7 @@ Once you validate its running, you can kill the process with Ctrl+C and continue
## Running Gunicorn with Supervisor
If you are following this guide, we already use [Supervisor](allianceauth.md#supervisor) to keep all of Alliance Auth components running. You don't _have to_ but we will be using it to start and run Gunicorn for consistency.
If you are following this guide, we already use [Supervisor](allianceauth.md#supervisor) to keep all of Alliance Auth's components running. You don't _have to_, but we will be using it to start and run Gunicorn for consistency.
### Sample Supervisor config
@ -51,7 +51,7 @@ stopsignal=INT
- `[program:gunicorn]` - Change `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=/home/allianceserver/venv/auth/bin/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.
- `command=/home/allianceserver/venv/auth/bin/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
@ -59,7 +59,7 @@ See the [Commonly Used Arguments](http://docs.gunicorn.org/en/latest/run.html#co
##### Where to bind Gunicorn to
What address are you going to use to reference it? By default, without a bind parameter, Gunicorn will bind to `127.0.0.1:8000`. This might be fine for your application. If it clashes with another application running on that port you will need to change it. I would suggest using UNIX sockets too, if you can.
What address are you going to use to reference it? By default, without a bind parameter, Gunicorn will bind to `127.0.0.1:8000`. This might be fine for your application. If it clashes with another application running on that port, you will need to change it. I would suggest using UNIX sockets too if you can.
For UNIX sockets add `--bind=unix:/run/allianceauth.sock` (or to a path you wish to use). Remember that your web server will need to be able to access this socket file.
@ -69,13 +69,13 @@ Whatever you decide to use, remember it because we'll need it when configuring y
##### Number of workers
By default Gunicorn will spawn only one worker. The number you set this to will depend on your own server environment, how many visitors you have etc. Gunicorn suggests `(2 x $num_cores) + 1` for the number of workers. So for example if you have 2 cores you want 2 x 2 + 1 = 5 workers. See [here](https://docs.gunicorn.org/en/stable/design.html#how-many-workers) for the official discussion on this topic.
By default, Gunicorn will spawn only one worker. The number you set this to will depend on your own server environment, how many visitors you have etc. Gunicorn suggests `(2 x $num_cores) + 1` for the number of workers. So, for example, if you have 2 cores, you want 2 x 2 + 1 = 5 workers. See [here](https://docs.gunicorn.org/en/stable/design.html#how-many-workers) for the official discussion on this topic.
Change it by adding `--workers=5` to the command.
##### Running with a virtual environment
Following this guide, you are running with a virtual environment. Therefore you'll need to add the path to the `command=` config line.
Following this guide, you are running with a virtual environment. Therefore, you'll need to add the path to the `command=` config line.
e.g. `command=/path/to/venv/bin/gunicorn myauth.wsgi`
@ -91,11 +91,11 @@ Once you have your configuration all sorted, you will need to reload your superv
## Configuring your webserver
Any web server capable of proxy passing should be able to sit in front of Gunicorn. Consult their documentation armed with your `--bind=` address and you should be able to find how to do it relatively easy.
Any web server capable of proxy passing should be able to sit in front of Gunicorn. Consult their documentation armed with your `--bind=` address, and you should be able to find how to do it relatively easily.
## 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:
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:
```shell
supervisorctl restart myauth:gunicorn

2
docs/installation/index.md
View File

@ -2,7 +2,7 @@
This chapter contains the main installation guides for **Alliance Auth**.
In addition to main guide for installation Alliance Auth you also find guides for configuring web servers (Apache, NGINX) and the recommended WSGI server (Gunicorn).
In addition to the main guide for installation Alliance Auth, you also find guides for configuring web servers (Apache, NGINX) and the recommended WSGI server (Gunicorn).
:::{toctree}
:maxdepth: 1

10
docs/installation/nginx.md
View File

@ -2,9 +2,9 @@
## Overview
Nginx (engine x) is a HTTP server known for its high performance, stability, simple configuration, and low resource consumption. Unlike traditional servers (i.e. Apache), Nginx doesn't rely on threads to serve requests, rather using an asynchronous event driven approach which permits predictable resource usage and performance under load.
Nginx (engine x) is an HTTP server known for its high performance, stability, simple configuration, and low-resource consumption. Unlike traditional servers (i.e., Apache), Nginx doesn't rely on threads to serve requests, rather using an asynchronous event-driven approach which permits predictable resource usage and performance under load.
If you're trying to cram Alliance Auth into a very small VPS of say, 1-2GB or less, then Nginx will be considerably friendlier to your resources compared to Apache.
If you're trying to cram Alliance Auth into a very small VPS of say, 1 to 2GB or less, then Nginx will be considerably friendlier to your resources compared to Apache.
You can read more about NGINX on the [NGINX wiki](https://www.nginx.com/resources/wiki/).
@ -12,7 +12,7 @@ You can read more about NGINX on the [NGINX wiki](https://www.nginx.com/resource
If you're converting from Apache, here are some things to consider.
Nginx is lightweight for a reason. It doesn't try to do everything internally and instead concentrates on just being a good HTTP server. This means that, unlike Apache, it won't automatically run PHP scripts via mod_php and doesn't have an internal WSGI server like mod_wsgi. That doesn't mean that it can't, just that it relies on external processes to run these instead. This might be good or bad depending on your outlook. It's good because it allows you to segment your applications, restarting Alliance Auth wont impact your PHP applications. On the other hand it means more config and more management of services. For some people it will be worth it, for others losing the centralised nature of Apache may not be worth it.
Nginx is lightweight for a reason. It doesn't try to do everything internally and instead concentrates on just being a good HTTP server. This means that, unlike Apache, it won't automatically run PHP scripts via mod_php and doesn't have an internal WSGI server like mod_wsgi. That doesn't mean that it can't, just that it relies on external processes to run these instead. This might be good or bad depending on your outlook. It's good because it allows you to segment your applications, restarting Alliance Auth won't impact your PHP applications. On the other hand, it means more config and more management of services. For some people it will be worth it, for others losing the centralised nature of Apache may not be worth it.
```{eval-rst}
+-----------+----------------------------------------+
@ -28,12 +28,12 @@ Your .htaccess files won't work. Nginx has a separate way of managing access to
## Setting up Nginx
Install Nginx via your preferred package manager or other method. If you need help just search, there are plenty of guides on installing Nginx out there.
Install Nginx via your preferred package manager or other method. If you need help, search, there are plenty of guides on installing Nginx out there.
Nginx needs to be able to read the folder containing your auth project's static files. `chown -R nginx:nginx /var/www/myauth/static`.
:::{tip}
Some specific distros may use ``www-data:www-data`` instead of ``nginx:nginx``, causing static files (images, stylesheets etc) not to appear. You can confirm what user Nginx will run under by checking either its base config file ``/etc/nginx/nginx.conf`` for the "user" setting, or once Nginx has started ``ps aux | grep nginx``.
Some specific distros may use ``www-data:www-data`` instead of ``nginx:nginx``, causing static files (images, stylesheets etc.) not to appear. You can confirm what user Nginx will run under by checking either its base config file ``/etc/nginx/nginx.conf`` for the "user" setting, or once Nginx has started ``ps aux | grep nginx``.
Adjust your chown commands to the correct user if needed.
:::

4
docs/installation/switch_to_non_root.md
View File

@ -1,12 +1,12 @@
# Switch to non-root
If you followed the official installation guide for Alliance Auth (AA) pre AA 3.x you usually ended up with a "root installation". A root installation means that you have installed AA with the root user and now need to log in as root every time to perform maintenance for AA, e.g. updating existing apps.
If you followed the official installation guide for Alliance Auth (AA) pre AA 3.x you usually ended up with a "root installation". A root installation means that you have installed AA with the root user and now need to log in as root every time to perform maintenance for AA, e.g., updating existing apps.
Since working as root is [generally not recommended](https://askubuntu.com/questions/16178/why-is-it-bad-to-log-in-as-root), this guide explains how you can easily migrate your existing "root installation" to a "non-root installation".
## How to switch to non-root
We will change the setup so that you can use your `allianceserver` user to perform most maintenance operations. In addition, you also need a sudo user for invoking root privileges, e.g. when restarting the AA services.
We will change the setup so that you can use your `allianceserver` user to perform most maintenance operations. In addition, you also need a sudo user for invoking root privileges, e.g., when restarting the AA services.
The migration itself is rather straightforward. The main idea is to change ownership for all relevant directories and files to `allianceserver`.

48
docs/installation/upgrade_python.md
View File

@ -2,7 +2,7 @@
This guide describes how to upgrade an existing Alliance Auth (AA) installation to a newer Python 3 version.
This guide shares many similarities with the Alliance Auth install guide, but it is targeted towards existing installs needing to update.
This guide shares many similarities with the Alliance Auth install guide, but it is targeted towards existing installations needing to update.
:::{note}
This guide will upgrade the software components only but not change any data or configuration.
@ -10,7 +10,7 @@ This guide will upgrade the software components only but not change any data or
## Install a new Python version
To run AA with a newer Python 3 version than your system's default you need to install it first. Technically it would be possible to upgrade your system's default Python 3, but since many of your system's tools have been tested to work with that specific version we would not recommend it. Instead we recommend to install an additional Python 3 version alongside your default version and use that for AA.
To run AA with a newer Python 3 version than your system's default, you need to install it first. Technically, it would be possible to upgrade your system's default Python 3, but since many of your system's tools have been tested to work with that specific version, we would not recommend it. Instead, we recommend installing an additional Python 3 version alongside your default version and using that for AA.
To install other Python versions than those included with your distribution, you need to add a new installation repository. Then you can install the specific Python 3 to your system.
@ -20,7 +20,7 @@ To install other Python versions than those included with your distribution, you
Centos Stream 8/9:
:::{note}
A Python 3.9 Package is available for Stream 8 and 9. You _may_ use this instead of building your own package. But our documentation will assume Python3.11 and you may need to substitute as neccessary
A Python 3.9 Package is available for Stream 8 and 9. You _may_ use this instead of building your own package. But our documentation will assume Python3.11, and you may need to substitute as necessary
sudo dnf install python39 python39-devel
:::
@ -77,12 +77,12 @@ sudo make altinstall
## Preparing your venv
Before updating your venv it is important to make sure that your current installation is stable. Otherwise your new venv might not be consistent with your data, which might create problems.
Before updating your venv, it is important to make sure that your current installation is stable. Otherwise, your new venv might not be consistent with your data, which might create problems.
Start by navigating to your main project folder (the one that has `manage.py` in it). If you followed the default installation the path is: `/home/allianceserver/myauth`
Start by navigating to your main project folder (the one that has `manage.py` in it). If you followed the default installation, the path is: `/home/allianceserver/myauth`
:::{note}
If you installed Alliance Auth under the allianceserver user, as reccommended. Remember to switch users for easier permission management::
If you installed Alliance Auth under the allianceserver user, as recommended. Remember to switch users for easier permission management::
:::
```bash
@ -121,9 +121,9 @@ supervisorctl restart myauth:
### Upgrade your apps
You also need to upgrade all additional apps to their newest version that you have installed. And you need to make sure that you can reinstall all your apps later, e.g. you know from which repo they came. We recommend to make a list of all your apps, so you can just go through them later when you rebuild your venv.
You also need to upgrade all additional apps to their newest version that you have installed. And you need to make sure that you can reinstall all your apps later, e.g., you know from which repo they came. We recommend making a list of all your apps, so you can go through them later when you rebuild your venv.
If you unsure which apps you have installed from repos check `INSTALLED_APPS` in your settings. Alternatively run this command to get a list all apps in your venv.
If you unsure which apps you have installed from repos check `INSTALLED_APPS` in your settings. Alternatively, run this command to get a list of all apps in your venv.
```shell
pip list
@ -149,13 +149,13 @@ python manage.py collectstatic
Do a final restart of your AA supervisors and make sure your installation is still running normally.
For a final check that they are no issues - e.g. any outstanding migrations - run this command:
For a final check that there are no issues - e.g., any outstanding migrations - run this command:
```shell
python manage.py check
```
If you get the following result you are good to go. Otherwise make sure to fix any issues first before proceeding.
If you get the following result, you are good to go. Otherwise, make sure to fix any issues first before proceeding.
```shell
System check identified no issues (0 silenced).
@ -165,22 +165,22 @@ System check identified no issues (0 silenced).
Make sure you are in your venv!
First we create a list of all installed packages in your venv. You can use this list later as reference to see what packages should be installed.
First, we create a list of all installed packages in your venv. You can use this list later as a reference to see what packages should be installed.
```shell
pip freeze > requirements.txt
```
At this point we recommend creating a list of the additional packages that you need to manually reinstall later on top of AA:
At this point, we recommend creating a list of the additional packages that you need to manually reinstall later on top of AA:
- Community AA apps (e.g. aa-structures)
- Additional tools you are using (e.g. flower, django-extensions)
- Additional tools you are using (e.g., flower, django-extensions)
:::{hint}
While `requirements.txt` will contain a complete list of your packages, it will also contain many packages that are automatically installed as dependencies and don't need be manually reinstalled.
While `requirements.txt` will contain a complete list of your packages, it will also contain many packages that are automatically installed as dependencies and don't need to be manually reinstalled.
:::
:::{note}
Some guide on the Internet will suggest to use use the requirements.txt file to recreate a venv. This is indeed possible, but only works if all packages can be installed from PyPI. Since most community apps are installed directly from repos this guide will not follow that approach.
Some guides on the Internet will suggest using the `requirements.txt` file to recreate a venv. This is indeed possible, but only works if all packages can be installed from PyPI. Since most community apps are installed directly from repos, this guide will not follow that approach.
:::
Leave the venv and shutdown all AA services:
@ -193,7 +193,7 @@ deactivate
supervisorctl stop myauth:
```
Rename and keep your old venv so we have a fallback in case of some unforeseeable issues:
Rename and keep your old venv, so we have a fallback in case of some unforeseeable issues:
```shell
mv /home/allianceserver/venv/auth /home/allianceserver/venv/auth_old
@ -233,37 +233,37 @@ pip install gunicorn
### Install all other packages
Last, but not least you need to reinstall all other packages, e.g. for AA community apps or additional tools.
Last, but not least, you need to reinstall all other packages, e.g., for AA community apps or additional tools.
Use the list of packages you created earlier as a checklist. Alternatively you use the `requirements.txt` file we created earlier to see what you need. During the installation process you can run `pip list` to see what you already got installed.
To check whether you are missing any apps you can also run the check command:
To check whether you are missing any apps, you can also run the check command:
```shell
python manage.py check
```
Note: In case you forget to install an app you will get this error
Note: In case you forget to install an app, you will get this error
```shell
ModuleNotFoundError: No module named 'xyz'
```
Note that you should not need to run any migrations unless you forgot to upgrade one of your existing apps or you got the newer version of an app through a dependency. In that case you just migrations normally.
Note that you should not need to run any migrations unless you forgot to upgrade one of your existing apps, or you got the newer version of an app through a dependency. In that case, you run migrations normally.
## Restart
After you have completed installing all packages just start your AA supervisor again.
After you have completed installing all packages, start your AA supervisor again.
```shell
supervisorctl start myauth:
```
We recommend to keep your old venv copy for a couple of days so you have a fallback just in case. After that you should be fine to remove it.
We recommend keeping your old venv copy for a couple of days, so you have a fallback just in case. After that, you should be fine to remove it.
## Fallback
In case you run into any major issue you can always switch back to your initial venv.
In case you run into any major issue, you can always switch back to your initial venv.
Before you start double-check that you still have your old venv for auth:
@ -271,7 +271,7 @@ Before you start double-check that you still have your old venv for auth:
ls /home/allianceserver/venv/auth /home/allianceserver/venv
```
If the output shows these two folders you should be safe to proceed:
If the output shows these two folders, you should be safe to proceed:
- `auth`
- `auth_old`

12
docs/maintenance/apps.md
View File

@ -11,7 +11,7 @@ Your auth project is just a regular Django project - you can add in [other Djang
## Removing Apps
The following instructions will explain how you can remove an app properly fom your Alliance Auth installation.
The following instructions will explain how you can remove an app properly from your Alliance Auth installation.
:::{note}
We recommend following these instructions to avoid dangling foreign keys or orphaned Python packages on your system, which might cause conflicts with other apps down the road.
@ -29,9 +29,9 @@ Let's first try the automatic approach by running the following command:
python manage.py migrate appname zero
```
If that worked you'll get a confirmation message.
If that works, you'll get a confirmation message.
If that did not work and you got error messages, you will need to remove the tables manually. This is pretty common btw, because many apps use sophisticated table setups, which can not be removed automatically by Django.
If that did not work, and you got error messages, you will need to remove the tables manually. This is pretty common btw, because many apps use sophisticated table setups, which cannot be removed automatically by Django.
#### Manual table removal
@ -48,7 +48,7 @@ sudo mysql -u root
use alliance_auth;
```
Next disable foreign key check. This makes it much easier to drop tables in any order.
Next, disable foreign key check. This makes it much easier to drop tables in any order.
```shell
SET FOREIGN_KEY_CHECKS=0;
@ -77,7 +77,7 @@ exit;
### Step 2 - Remove the app from Alliance Auth
Once the tables have been removed, you you can remove the app from Alliance Auth. This is done by removing the applabel from the `INSTALLED_APPS` list in your local settings file.
Once the tables have been removed, you can remove the app from Alliance Auth. This is done by removing the applabel from the `INSTALLED_APPS` list in your local settings file.
### Step 3 - Remove the Python package
@ -101,4 +101,4 @@ python manage.py remove_stale_contenttypes --include-stale-apps
This inbuilt Django command will step through each contenttype and offer to delete it, displaying what exactly this will cascade to delete. Pay attention and ensure you understand exactly what is being removed before answering `yes`.
This should only cleanup uninstalled apps, deprecated permissions within apps should be cleaned up using Data Migrations by each responsible application.
This should only clean up uninstalled apps, deprecated permissions within apps should be cleaned up using Data Migrations by each responsible application.

2
docs/maintenance/index.md
View File

@ -1,6 +1,6 @@
# Maintenance
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.
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.
:::{toctree}
:maxdepth: 1

8
docs/maintenance/project.md
View File

@ -1,6 +1,6 @@
# 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.
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
@ -26,9 +26,9 @@ And finally the settings folder.
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 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.
The local settings file is referred to as "your auth project's settings file" and you are instructed to edit it during the installation 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
@ -39,4 +39,4 @@ Your auth project comes with four log file definitions by default. These are cre
- `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.
When asking for assistance with your auth project, be sure to first read the logs, and share any relevant entries.

10
docs/maintenance/troubleshooting.md
View File

@ -2,13 +2,13 @@
## 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`.
In its default configuration, your auth project logs INFO and higher 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`.
To record DEBUG messages in the log file, alter a setting in your auth project's settings file: `LOGGING['handlers']['log_file']['level'] = 'DEBUG'`. After restarting gunicorn and celery your log file will record all logging messages.
To record DEBUG messages in the log file, alter a setting in your auth project's settings file: `LOGGING['handlers']['log_file']['level'] = 'DEBUG'`. After restarting gunicorn and celery, your log file will record all logging messages.
## Common Problems
### I'm getting an error 500 trying to connect to the website on a new install
### I'm getting error 500 when trying to connect to the website on a new installation
*Great.* Error 500 is the generic message given by your web server when *anything* breaks. The actual error message is hidden in one of your auth project's log files. Read them to identify it.
@ -39,7 +39,7 @@ This usually indicates an issue with your email settings. Ensure these are corre
### No images are available to users accessing the website
This is likely due to a permissions mismatch. Check the setup guide for your web server. Additionally ensure the user who owns `/var/www/myauth/static` is the same user as running your webserver, as this can be non-standard.
This is likely due to a permission mismatch. Check the setup guide for your web server. Additionally ensure the user who owns `/var/www/myauth/static` is the same user as running your webserver, as this can be non-standard.
### Unable to execute 'gunicorn myauth.wsgi' or ImportError: No module named 'myauth.wsgi'
@ -55,4 +55,4 @@ 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.
Install a newer Maria DB version to fix this issue another DBMS supported by Django 2.2.

24
docs/maintenance/tuning/celery.md
View File

@ -1,7 +1,7 @@
# Celery
:::{hint}
Most tunings will require a change to your supervisor configuration in your `supervisor.conf` file. Note that you need to restart the supervisor daemon in order for any changes to take effect. And before restarting the daemon you may want to make sure your supervisors stop gracefully:(Ubuntu):
Most tunings will require a change to your supervisor configuration in your `supervisor.conf` file. Note that you need to restart the supervisor daemon in order for any changes to take effect. And before restarting the daemon, you may want to make sure your supervisors stop gracefully:(Ubuntu):
```bash
supervisor stop myauth:
@ -12,7 +12,7 @@ systemctl supervisor restart
## Task Logging
By default task logging is deactivated. Enabling task logging allows you to monitor what tasks are doing in addition to getting all warnings and error messages. To enable info logging for tasks add the following to the command configuration of your worker in the `supervisor.conf` file:
By default, task logging is deactivated. Enabling task logging allows you to monitor what tasks are doing in addition to getting all warnings and error messages. To enable info logging for tasks, add the following to the command configuration of your worker in the `supervisor.conf` file:
```ini
-l info
@ -26,7 +26,7 @@ command=/home/allianceserver/venv/auth/bin/celery -A myauth worker -l info
## Protection against memory leaks
Celery workers often have memory leaks and will therefore grow in size over time. While the Alliance Auth team is working hard to ensure Auth is free of memory leaks some may still be cause by bugs in different versions of libraries or community apps. It is therefore good practice to enable features that protect against potential memory leaks.
Celery workers often have memory leaks and will therefore grow in size over time. While the Alliance Auth team is working hard to ensure Auth is free of memory leaks, some may still be caused by bugs in different versions of libraries or community apps. It is therefore good practice to enable features that protect against potential memory leaks.
:::{hint}
The 256 MB limit is just an example and should be adjusted to your system configuration. We would suggest to not go below 128MB though, since new workers start with around 80 MB already. Also take into consideration that this value is per worker and that you may have more than one worker running in your system.
@ -36,9 +36,9 @@ The 256 MB limit is just an example and should be adjusted to your system config
It is also possible to configure your supervisor to monitor and automatically restart programs that exceed a memory threshold.
This is not a built in feature and requires the 3rd party extension [superlance](https://superlance.readthedocs.io/en/latest/), which includes a set of plugin utilities for supervisor. The one that watches memory consumption is [memmon](https://superlance.readthedocs.io/en/latest/memmon.html).
This is not a built-in feature and requires the 3rd party extension [superlance](https://superlance.readthedocs.io/en/latest/), which includes a set of plugin utilities for supervisor. The one that watches memory consumption is [memmon](https://superlance.readthedocs.io/en/latest/memmon.html).
To setup install superlance into your venv with:
To install superlance into your venv, run:
```shell
pip install superlance
@ -53,13 +53,13 @@ directory=/home/allianceserver/myauth
events=TICK_60
```
This setup will check the memory consumption of the program "worker" every 60 secs and automatically restart it if is goes above 256 MB. Note that it will use the stop signal configured in supervisor, which is `TERM` by default. `TERM` will cause a "warm shutdown" of your worker, so all currently running tasks are completed before the restart.
This setup will check the memory consumption of the program "worker" every 60 secs and automatically restart it if it goes above 256 MB. Note that it will use the stop signal configured in supervisor, which is `TERM` by default. `TERM` will cause a "warm shutdown" of your worker, so all currently running tasks are completed before the restart.
Again, the 256 MB is just an example and should be adjusted to fit your system configuration.
## Increasing task throughput
Celery tasks are designed to run concurrently, so one obvious way to increase task throughput is run more tasks in parallel. The default celery worker configuration will allow either of these options to be configured out of the box.
Celery tasks are designed to run concurrently, so one obvious way to increase task throughput is to run more tasks in parallel. The default celery worker configuration will allow either of these options to be configured out of the box.
### Extra Worker Threads
@ -73,13 +73,13 @@ process_name=%(program_name)s_%(process_num)02d
...
```
This number will be multiplied by your concurrency setting,
This number will be multiplied by your concurrency setting. For example:
```text
numprocs * concurency = workers
```
increasing this number will require a modification to the memmon settings as each `numproc` worker will get a unique name for example with `numproc=3`
Increasing this number will require a modification to the memmon settings as each `numproc` worker will get a unique name for example with `numproc=3`
```ini
[eventlistener:memmon]
@ -89,7 +89,7 @@ command=... -p worker_00=256MB -p worker_01=256MB -p worker_02=256MB
```
:::{hint}
You will want to experiment with different settings to find the optimal. One way to generate task load and verify your configuration is to run a model update with the following command:
You will want to experiment with different settings to find the optimal. One way to generate some task load and verify your configuration is to run a model update with the following command:
```bash
celery -A myauth call allianceauth.eveonline.tasks.run_model_update
@ -106,7 +106,7 @@ This can be achieved by the setting the concurrency parameter of the celery work
```
:::{hint}
The optimal number will hugely depend on your individual system configuration and you may want to experiment with different settings to find the optimal. One way to generate task load and verify your configuration is to run a model update with the following command:
The optimal number will hugely depend on your individual system configuration, and you may want to experiment with different settings to find the optimal. One way to generate some task load and verify your configuration is to run a model update with the following command:
```bash
celery -A myauth call allianceauth.eveonline.tasks.run_model_update
@ -115,5 +115,5 @@ celery -A myauth call allianceauth.eveonline.tasks.run_model_update
:::
:::{hint}
The optimal number of concurrent workers will be different for every system and we recommend experimenting with different figures to find the optimal for your system. Note, that the example of 10 threads is conservative and should work even with smaller systems.
The optimal number of concurrent workers will be different for every system, and we recommend experimenting with different figures to find the optimal for your system. Note that the example of 10 threads is conservative and should work even with smaller systems.
:::

6
docs/maintenance/tuning/gunicorn.md
View File

@ -2,11 +2,11 @@
## Number of workers
The default installation will have 3 workers configured for Gunicorn. This will be fine on most system, but if your system as more than one core than you might want to increase the number of workers to get better response times. Note that more workers will also need more RAM though.
The default installation will have 3 workers configured for Gunicorn. This will be fine on most systems, but if your system as more than one core than you might want to increase the number of workers to get better response times. Note that more workers will also need more RAM though.
The number you set this to will depend on your own server environment, how many visitors you have etc. Gunicorn suggests `(2 x $num_cores) + 1` for the number of workers. So for example if you have 2 cores you want 2 x 2 + 1 = 5 workers. See [here](https://docs.gunicorn.org/en/stable/design.html#how-many-workers) for the official discussion on this topic.
The number you set this to will depend on your own server environment, how many visitors you have etc. Gunicorn suggests `(2 x $num_cores) + 1` for the number of workers. So for example, if you have 2 cores, you want 2 x 2 + 1 = 5 workers. See [here](https://docs.gunicorn.org/en/stable/design.html#how-many-workers) for the official discussion on this topic.
For example to get 5 workers change the setting `--workers=5` in your `supervisor.conf` file and then reload the supervisor with the following command to activate the change (Ubuntu):
For example, to get 5 workers change the setting `--workers=5` in your `supervisor.conf` file and then reload the supervisor with the following command to activate the change (Ubuntu):
```shell
systemctl restart supervisor

4
docs/maintenance/tuning/index.md
View File

@ -1,9 +1,9 @@
# Tuning
The official installation guide will install a stable version of Alliance Auth that will work fine for most cases. However, there are a lot of levels that can be used to optimize a system. For example some installations may we short on RAM and want to reduce the total memory footprint, even though that may reduce system performance. Others are fine with further increasing the memory footprint to get better system performance.
The official installation guide will install a stable version of Alliance Auth that will work fine for most cases. However, there are a lot of levels that can be used to optimize a system. For example, some installations may we short on RAM and want to reduce the total memory footprint, even though that may reduce system performance. Others are fine with further increasing the memory footprint to get better system performance.
:::{warning}
Tuning usually has benefits and costs and should only be performed by experienced Linux administrators who understand the impact of tuning decisions on to their system.
Tuning usually has benefits and costs and should only be performed by experienced Linux administrators who understand the impact of tuning decisions on their system.
:::
:::{toctree}

4
docs/maintenance/tuning/python.md
View File

@ -6,9 +6,9 @@ Newer versions of python can focus heavily on performance improvements, some mor
As a general rule, Python 3.9 and Python 3.11 both had a strong focus on performance improvements. Python 3.12 is looking promising but has yet to have widespread testing, adoption and deployment. A simple comparison is available at [speed.python.org](https://speed.python.org/comparison/?exe=12%2BL%2B3.11%2C12%2BL%2B3.12%2C12%2BL%2B3.10%2C12%2BL%2B3.9%2C12%2BL%2B3.8&ben=746&env=1&hor=false&bas=none&chart=normal+bars).
[Djangobench](https://github.com/django/djangobench/tree/master) is source of synthetic benchmarks and a useful tool for running comparisons. Below are some examples to inform your investigations.
[Djangobench](https://github.com/django/djangobench/tree/master) is the source of synthetic benchmarks and a useful tool for running comparisons. Below are some examples to inform your investigations.
Keep in mind while a 1.2x faster result is significant, it's only one step of the process, Celery, SQL, Redis and many other factors will influence the end result and this _python_ speed improvement will not translate 1:1 into real world performance.
Keep in mind while a 1.2x faster result is significant, it's only one step of the process, Celery, SQL, Redis, and many other factors will influence the endresult, and this _python_ speed improvement will not translate 1:1 into real world performance.
### Django 4.0.10

24
docs/maintenance/tuning/sql.md
View File

@ -2,15 +2,15 @@
SQL Tuning is usually the realm of experienced Database Admins, as it can be full of missteps leading to worse performance. It is _extremely_ important that you take it slowly, make one change at a time with dedicated research and test before and after.
Before you start down this path its best to update [MariaDB](https://mariadb.org/download/?t=repo-config) / MySQL. Performance Schemas, some default tuning and other general performance improvements are only available on new versions. You must also allow your server to run for 24 hours at least to gather accurate data.
Before you start down this path, it's best to update [MariaDB](https://mariadb.org/download/?t=repo-config) / MySQL. Performance Schemas, some default tuning and other general performance improvements are only available on new versions. You must also allow your server to run for 24 hours at least to gather accurate data.
## MySQLTuner
[MySQLTuner](https://github.com/major/MySQLTuner-perl) is a Perl script that will analyze inbuilt metrics and spit out recommendations.
[MySQLTuner](https://github.com/major/MySQLTuner-perl) is a Perl script that will analyze inbuilt metrics and provide recommendations.
### [performance_schema](https://mariadb.com/kb/en/performance-schema-system-variables/#performance_schema)
This should be ON for 24 hours before applying any recommendations, then can be turned _OFF_ to save Memory while its not needed.
This should be ON for 24 hours before applying any recommendations, then can be turned _OFF_ to save Memory while it's not needed.
```bash
-------- Performance schema ------------------------------------------------------------------------
@ -30,7 +30,7 @@ Note you must use 127.0.0.1 for localhost connections, and all entries in GRANT
### [table_definition_cache](https://mariadb.com/kb/en/server-system-variables/#table_definition_cache)
Will usually need to be expanded on installs with many extensions
Usually need to be expanded on installations with many extensions.
Most installs should cache all their tables, but if your hit rate is still quite high, you may have a lot of rarely used tables that you don't need to waste memory caching.
@ -49,9 +49,9 @@ table_definition_cache (400) > 567 or -1 (autosizing if supported)
### [innodb_buffer_pool_size](https://mariadb.com/kb/en/innodb-system-variables/#innodb_buffer_pool_size)
This is in short, the amount of memory assigned to store data for faster reads. If you are memory starved you should not increase this variable regardless of the suggestions of this tool. Pushing SQL cache to pagefile will not result in faster queries.
This is in short, the amount of memory assigned to store data for faster reads. If you are memory starved, you should not increase this variable regardless of the suggestions of this tool. Pushing SQL cache to pagefile will not result in faster queries.
If you are not memory starved, you can wind this up to the amount of total data you have to store it all in memory. This would be a significant performance increase for larger installs on dedicated hardware with memory to spare.
If you are not memory starved, you can wind this up to the amount of total data you have to store it all in memory. This would be a significant performance increase for larger installations on dedicated hardware with memory to spare.
```bash
[!!] InnoDB buffer pool / data size: 128.0M / 651.6M
@ -67,7 +67,7 @@ If you are not memory starved, you can wind this up to the amount of total data
[innodb_log_file_size](https://mariadb.com/kb/en/innodb-system-variables/#innodb_log_file_size) This is your _write_ log, used to redo any commits in the event of a crash. MySQLTuner recommends this be 1/4 of your innodb_buffer_pool / read buffer. I would not lower this past the default size.
[innodb_log_buffer_size](https://mariadb.com/kb/en/innodb-system-variables/#innodb_log_buffer_size) This is the memory buffer for the write log. Larger transactions will benefit from a larger setting.
[innodb_log_buffer_size](https://mariadb.com/kb/en/innodb-system-variables/#innodb_log_buffer_size) This is the memory buffer for the "write" log. Larger transactions will benefit from a larger setting.
```bash
[!!] Ratio InnoDB log file size / InnoDB Buffer pool size (75%): 96.0M \* 1 / 128.0M should be equal to 25%
@ -79,7 +79,7 @@ If you are not memory starved, you can wind this up to the amount of total data
### [innodb_file_per_table](https://mariadb.com/kb/en/innodb-system-variables/#innodb_file_per_table)
This is not for performance, but for file system utilization and ease of use. While off all tables are stored in a single monolith file, as opposed to individual files. This is deprecated and set to ON in MariaDB 11.x
This is not for performance, but for file system utilization and ease of use. While off, all tables are stored in a single monolith file, as opposed to individual files. This is deprecated and set to ON in MariaDB 11.x
```bash
[OK] InnoDB File per table is activated
@ -87,7 +87,7 @@ This is not for performance, but for file system utilization and ease of use. Wh
### [join_buffer_size](https://mariadb.com/kb/en/server-system-variables/#join_buffer_size)
It is always better to optimize a table with indexes, if you have valuable performance data and analysis please reach out to either the Alliance Auth or Community dev responsible for the data that could benefit from indexes. MySQLTuner will likely recommend increasing this number for as long as there are any queries that could benefit, regardless of their resulting performance impact.
It is always better to optimize a table with indexes, if you have valuable performance data and analysis, please reach out to either the Alliance Auth or Community dev responsible for the data that could benefit from indexes. MySQLTuner will likely recommend increasing this number for as long as there are any queries that could benefit, regardless of their resulting performance impact.
Also keep in mind this is _per thread_, if you have a potential 200 connections, 256KB * 200 = 50MB, scaling this setting out too far can result in more memory use than expected.
@ -121,7 +121,7 @@ tmp_table_size and max_heap_table_size should be increased together.
Index buffer for MyISAM tables, If you use no or very little data in MyISAM tables. You may reclaim some memory here
In this example we still have some MyISAM tables, you may have none
In this example, we still have some MyISAM tables. You may have none.
```bash
[--] General MyIsam metrics:
@ -152,7 +152,7 @@ Index and data buffer for Aria tables, If you use no or very little data in Aria
## Swappiness
Swappiness is not an SQL variable but part of your system kernel. Swappiness controls how much free memory a server "likes" to have at any given time, and how frequently it shifts data to swapfile in order to free up memory. Desktop operating systems will have this value set quite high, whereas servers are less aggressive with their swapfile.
Swappiness is not an SQL variable but part of your system kernel. Swappiness controls how much free memory a server "likes" to have at any given time, and how frequently it shifts data to swapfile to free up memory. Desktop operating systems will have this value set quite high, whereas servers are less aggressive with their swapfile.
Database workloads especially benefit from having their caches stay in memory and will recommend values under 10 for a dedicated database server. 10 is a good compromise for a mixed use server with adequate memory.
@ -193,7 +193,7 @@ vm.swappiness <= 10 (echo 10 > /proc/sys/vm/swappiness) or vm.swappiness=10 in /
## Max Asynchronous IO
Unless you are still operating on spinning rust (Hard Disk Drives), or an IO limited VPS, you can likely increase this value. Database workloads appreciate the additional scaling.
Unless you are still operating on spinning rust (Hard Disk Drives), or an IO-limited VPS, you can likely increase this value. Database workloads appreciate the additional scaling.
```bash
[--] Information about kernel tuning:

2
docs/support/index.md
View File

@ -1,6 +1,6 @@
# Support
If you encounter any AA related issues during installation or otherwise please first check the following resources:
If you encounter any AA related issues during installation or otherwise, please first check the following resources:
- See the section on [troubleshooting](/maintenance/troubleshooting.md) your AA instance, e.g. the list of common problems
- Search the AA [issue list](https://gitlab.com/allianceauth/allianceauth/issues?scope=all&utf8=%E2%9C%93&state=all&search=my+issue) (especially the closed ones)