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

editorconfig applied

Browse Source
This commit is contained in:
Peter Pfeufer
2021-05-17 11:42:28 +02:00
parent bad36a69e8
commit e6a4cea4de
99 changed files with 522 additions and 600 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/conf.py
View File

@@ -142,8 +142,7 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'AllianceAuth.tex', u'Alliance Auth Documentation',
u'R4stl1n', 'manual'),
(master_doc, 'AllianceAuth.tex', u'Alliance Auth Documentation', u'R4stl1n', 'manual'),
]
@@ -153,7 +152,7 @@ latex_documents = [
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'allianceauth', u'Alliance Auth Documentation',
[author], 1)
[author], 1)
]
# -- Options for autodoc -------------------------------------------------
@@ -167,8 +166,8 @@ add_module_names = False
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'AllianceAuth', u'Alliance Auth Documentation',
author, 'AllianceAuth', 'An auth system for EVE Online to help in-game organizations manage online service access.',
'Miscellaneous'),
author, 'AllianceAuth', 'An auth system for EVE Online to help in-game organizations manage online service access.',
'Miscellaneous'),
]
def setup(app):

2
docs/customizing/index.md
View File

@@ -4,7 +4,7 @@ It is possible to customize your **Alliance Auth** instance.
```eval_rst
.. warning::
Keep in mind that you may need to update some of your customizations manually after new 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

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

@@ -1,8 +1,8 @@
# Alliance Auth documentation
The documentation for Alliance Auth uses [Sphinx](http://www.sphinx-doc.org/) to build documentation. When a new commit
to specific branches is made (master, primarily), the repository is automatically pulled, docs built and deployed on
[readthedocs.org](https://readthedocs.org/).
to specific branches is made (master, primarily), the repository is automatically pulled, docs built and deployed on
[readthedocs.org](https://readthedocs.org/).
Documentation was migrated from the GitHub wiki pages and into the repository to allow documentation changes to be

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

@@ -21,18 +21,18 @@ Typically a service will contain 5 key components:
The architecture looks something like this:
urls -------▶ Views
▲ |
| |
| ▼
ServiceHook ----▶ Tasks ----▶ Manager
▲
|
|
AllianceAuth
▲ |
| |
| ▼
ServiceHook ----▶ Tasks ----▶ Manager
▲
|
|
AllianceAuth
Where:
Module --▶ Dependency/Import
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.

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

@@ -42,9 +42,9 @@ This is a great feature to signal the user, that he has some open issues to take
```eval_rst
.. 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.
2. If there are currently no open items, do not show a badge at all.
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.
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:

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

@@ -8,7 +8,7 @@ In addition all tools described in this guide are open source or free software.
```eval_rst
.. 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
@@ -27,7 +27,7 @@ We will use the build-in Django development webserver, so we don't need to setup
```eval_rst
.. 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
@@ -75,13 +75,13 @@ For AA we want to develop with Python 3.6, because that provides the maximum com
```eval_rst
.. hint::
To check your system's Python 3 version you can enter: ``python3 --version``
To check your system's Python 3 version you can enter: ``python3 --version``
```
```eval_rst
.. 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 supported by AA, e.g Python 3.6
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 setup your dev environment with the oldest Python 3 version supported by AA, e.g Python 3.6
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.
```
Use the following command to install Python 3 with all required libraries with the default version:
@@ -100,7 +100,7 @@ sudo apt-get install mysql-server mysql-client libmysqlclient-dev
```eval_rst
.. note::
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 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:
@@ -150,14 +150,14 @@ sudo redis-server --daemonize yes
```eval_rst
.. note::
WSL does not have an init.d service, so it will not automatically start your services such as MySQL and Redis when you boot your Windows machine. For convenience we recommend putting the commands for starting these services in a bash script. Here is an example: ::
WSL does not have an init.d service, so it will not automatically start your services such as MySQL and Redis when you boot your Windows machine. For convenience we recommend putting the commands for starting these services in a bash script. Here is an example: ::
#/bin/bash
# start services for AA dev
sudo service mysql start
sudo redis-server --daemonize yes
#/bin/bash
# start services for AA dev
sudo service mysql start
sudo redis-server --daemonize yes
In addition it is possible to configure Windows to automatically start WSL services, but that procedure goes beyond the scopes of this guide.
In addition it is possible to configure Windows to automatically start WSL services, but that procedure goes beyond the scopes of this guide.
```
### Setup dev folder on WSL
@@ -299,15 +299,15 @@ Once running you can access your auth site on the browser under `http://localhos
```eval_rst
.. 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).
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).
```
```eval_rst
.. 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.
**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.
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. Just start your server with the following option: ``python manage.py runserver --insecure``
```
### Celery

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

@@ -16,7 +16,7 @@ As a rule of thumb we therefore recommend to use celery tasks for every process
```eval_rst
.. 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
@@ -108,11 +108,11 @@ The list of task signatures is then converted to a chain and started asynchronou
```eval_rst
.. hint::
In our example we use ``si()``, which is a shortcut for "immutable signatures" and prevents us from having to deal with result sharing between tasks.
In our example we use ``si()``, which is a shortcut for "immutable signatures" and prevents us from having to deal with result sharing between tasks.
For more information on signature and work flows see the official documentation on `Canvas <https://docs.celeryproject.org/en/latest/userguide/canvas.html>`_.
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?
@@ -152,14 +152,14 @@ In Alliance Auth we have defined task priorities from 0 - 9 as follows:
```eval_rst
.. 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.
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 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)
```
```eval_rst
.. 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.
@@ -172,7 +172,7 @@ example.apply_async(priority=3)
```eval_rst
.. 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 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.
```
## What special features should I be aware of?

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

@@ -32,7 +32,7 @@ CELERYBEAT_SCHEDULE['discord.update_all_usernames'] = {
```eval_rst
.. 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 the values for these settings, e.g. your Discord server ID (aka guild ID), later in the setup process.
```
### Creating a Server
@@ -47,7 +47,7 @@ Update your auth project's settings file, inputting the server ID as `DISCORD_GU
```eval_rst
.. 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
@@ -115,7 +115,7 @@ Name Description
```eval_rst
.. note::
Depending on how many users you have, running these tasks can take considerable time to finish. You can calculate roughly 1 sec per user for all tasks, except update_all, which needs roughly 3 secs per user.
Depending on how many users you have, running these tasks can take considerable time to finish. You can calculate roughly 1 sec per user for all tasks, except update_all, which needs roughly 3 secs per user.
```
## Settings

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

@@ -4,17 +4,17 @@ Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all
```eval_rst
.. 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.
```
```eval_rst
.. note::
Same as the official installation guide this guide is assuming you are performing all steps as ``root`` user.
Same as the official installation guide this guide is assuming you are performing all steps as ``root`` user.
```
```eval_rst
.. warning::
This guide is currently for Ubuntu only.
This guide is currently for Ubuntu only.
```
## Installations

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

@@ -1,6 +1,6 @@
# Openfire
Openfire is a Jabber (XMPP) server.
Openfire is a Jabber (XMPP) server.
## Prepare Your Settings

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

@@ -74,7 +74,7 @@ Nginx: `chown -R nginx:nginx /var/www/forums`
```eval_rst
.. 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.
..
```

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

@@ -11,8 +11,8 @@ SMF requires PHP installed in your web server. Apache has `mod_php`, NGINX requi
## Prepare Your Settings
In your auth project's settings file, do the following:
- Add `'allianceauth.services.modules.smf',` to your `INSTALLED_APPS` list
- Append the following to the bottom of the settings file:
- Add `'allianceauth.services.modules.smf',` to your `INSTALLED_APPS` list
- Append the following to the bottom of the settings file:
```python
# SMF Configuration
@@ -36,15 +36,19 @@ Using your browser, you can download the latest version of SMF to your desktop c
Download using wget, replacing the URL with the URL for the package you just retrieved
wget https://download.simplemachines.org/index.php?thanks;filename=smf_2-0-15_install.zip
```shell
wget https://download.simplemachines.org/index.php?thanks;filename=smf_2-0-15_install.zip
```
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
unzip smf_2-0-15_install.zip
```shell
unzip smf_2-0-15_install.zip
````
Now we need to move this to our web directory. Usually `/var/www/forums`.
mv smf /var/www/forums
```shell
mv smf /var/www/forums
````
The web server needs read/write permission to this folder
@@ -53,18 +57,22 @@ Nginx: `chown -R nginx:nginx /var/www/forums`
```eval_rst
.. 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
SMF needs a database. Create one:
```shell
mysql -u root -p
```
mysql -u root -p
create database alliance_smf;
grant all privileges on alliance_smf . * to 'allianceserver'@'localhost';
exit;
```mysql
create database alliance_smf;
grant all privileges on alliance_smf . * to 'allianceserver'@'localhost';
exit;
```
Enter the database information into the `DATABASES['smf']` section of your auth project's settings file.
@@ -73,33 +81,34 @@ Enter the database information into the `DATABASES['smf']` section of your auth
Your web server needs to be configured to serve SMF.
A minimal Apache config might look like:
<VirtualHost *:80>
ServerName forums.example.com
DocumentRoot /var/www/forums
<Directory "/var/www/forums">
DirectoryIndex index.php
</Directory>
</VirtualHost>
```apache
<VirtualHost *:80>
ServerName forums.example.com
DocumentRoot /var/www/forums
<Directory "/var/www/forums">
DirectoryIndex index.php
</Directory>
</VirtualHost>
````
A minimal Nginx config might look like:
```nginx
server {
listen 80;
server_name forums.example.com;
root /var/www/forums;
index index.php;
access_log /var/logs/forums.access.log;
server {
listen 80;
server_name forums.example.com;
root /var/www/forums;
index index.php;
access_log /var/logs/forums.access.log;
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/tmp/php.socket;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/tmp/php.socket;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
````
Enter the web address to your forums into the `SMF_URL` setting in your auth project's settings file.
### Web Install

34
docs/installation/allianceauth.md
View File

@@ -4,12 +4,12 @@ This document describes how to install **Alliance Auth** from scratch.
```eval_rst
.. tip::
If you are uncomfortable with Linux permissions follow the steps below as the root user.
If you are uncomfortable with Linux permissions follow the steps below as the root user.
```
```eval_rst
.. note::
There are additional installation steps for activating services and apps that come with **Alliance Auth**. Please see the page for the respective service or apps in chapter :doc:`/features/index` for details.
There are additional installation steps for activating services and apps that come with **Alliance Auth**. Please see the page for the respective service or apps in chapter :doc:`/features/index` for details.
```
## Dependencies
@@ -20,7 +20,7 @@ Alliance Auth can be installed on any Unix like operating system. Dependencies a
```eval_rst
.. hint::
CentOS: A few packages are included in a non-default repository. Add it and update the package lists. ::
CentOS: A few packages are included in a non-default repository. Add it and update the package lists. ::
yum -y install https://centos7.iuscommunity.org/ius-release.rpm
yum update
@@ -48,9 +48,9 @@ It's recommended to use a database service instead of SQLite. Many options are a
```eval_rst
.. warning::
Many Ubuntu distributions come with an older version of Maria DB, which is not compatible with **Alliance Auth**. You need Maria DB 10.3 or higher!
Many Ubuntu distributions come with an older version of Maria DB, which is not compatible with **Alliance Auth**. You need Maria DB 10.3 or higher!
For instructions on how To install a newer version of Maria DB on Ubuntu visit this page: `MariaDB Repositories <https://downloads.mariadb.org/mariadb/repositories/#distro=Ubuntu&mirror=osuosl>`_.
For instructions on how To install a newer version of Maria DB on Ubuntu visit this page: `MariaDB Repositories <https://downloads.mariadb.org/mariadb/repositories/#distro=Ubuntu&mirror=osuosl>`_.
```
Ubuntu:
@@ -67,7 +67,7 @@ yum install mariadb-server mariadb-devel mariadb-shared mariadb
```eval_rst
.. note::
If you don't plan on running the database on the same server as auth you still need to install the libmysqlclient-dev package on Ubuntu or mariadb-devel package on CentOS.
If you don't plan on running the database on the same server as auth you still need to install the libmysqlclient-dev package on Ubuntu or mariadb-devel package on CentOS.
```
### Redis and Other Tools
@@ -88,7 +88,7 @@ yum install gcc gcc-c++ unzip git redis curl bzip2-devel
```eval_rst
.. important::
CentOS: Make sure Redis is running before continuing. ::
CentOS: Make sure Redis is running before continuing. ::
systemctl enable redis.service
systemctl start redis.service
@@ -112,11 +112,11 @@ mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql
```eval_rst
.. note::
You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the ``time_zone`` tables::
You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the ``time_zone`` tables::
mysql -u root -p
use mysql;
show tables;
mysql -u root -p
use mysql;
show tables;
```
Close the SQL shell and secure your database server with this command:
@@ -153,12 +153,12 @@ python3 -m venv /home/allianceserver/venv/auth/
```eval_rst
.. warning::
The python3 command may not be available on all installations. Try a specific version such as ``python3.6`` if this is the case.
The python3 command may not be available on all installations. Try a specific version such as ``python3.6`` if this is the case.
```
```eval_rst
.. tip::
A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the Python_ docs.
A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the Python_ docs.
.. _Python: https://docs.python.org/3/library/venv.html
```
@@ -170,7 +170,7 @@ source /home/allianceserver/venv/auth/bin/activate
```eval_rst
.. hint::
Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first. When finished, deactivate it with the ``deactivate`` command.
Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first. When finished, deactivate it with the ``deactivate`` command.
```
### Eve Online SSO
@@ -258,7 +258,7 @@ The default configuration is good enough for most installations. Additional info
```eval_rst
.. note::
Many package managers will install Supervisor 3 by default, which requires Python 2.
Many package managers will install Supervisor 3 by default, which requires Python 2.
```
Ubuntu:
@@ -295,9 +295,9 @@ You can check the status of the processes with `supervisorctl status`. Logs from
```eval_rst
.. 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. ::
supervisorctl restart myauth:
supervisorctl restart myauth:
```
## Webserver

2
docs/installation/gunicorn.md
View File

@@ -8,7 +8,7 @@ Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html
```eval_rst
.. 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 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.
```
## Setting up Gunicorn

4
docs/installation/nginx.md
View File

@@ -35,8 +35,8 @@ Nginx needs to be able to read the folder containing your auth project's static
```eval_rst
.. 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`.
Adjust your chown commands to the correct user if needed.
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.
..
```

12
docs/installation/upgrade_python.md
View File

@@ -4,12 +4,12 @@ This guide describes how to upgrade an existing Alliance Auth (AA) installation
```eval_rst
.. hint::
In accordance with the installation guide we will assume you perform all actions as root. If you are not running as root you need to add ``sudo`` to some commands.
In accordance with the installation guide we will assume you perform all actions as root. If you are not running as root you need to add ``sudo`` to some commands.
```
```eval_rst
.. note::
This guide will upgrade the software components only but not change any data or configuration.
This guide will upgrade the software components only but not change any data or configuration.
```
## Install a new Python version
@@ -18,7 +18,7 @@ To run AA with a newer Python 3 version than your system's default you need to i
```eval_rst
.. note::
For stability and performance we currently recommend to run AA with Python 3.7. It has proven to be the fastest and most stable version in use currently.
For stability and performance we currently recommend to run AA with Python 3.7. It has proven to be the fastest and most stable version in use currently.
```
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.
@@ -27,7 +27,7 @@ Ubuntu 1604 1804:
```eval_rst
.. note::
Ubuntu 2004 ships with Python 3.8, No updates required.
Ubuntu 2004 ships with Python 3.8, No updates required.
```
```bash
@@ -156,12 +156,12 @@ At this point we recommend creating a list of the additional packages that you n
```eval_rst
.. 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 be manually reinstalled.
```
```eval_rst
.. 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 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.
```
Leave the venv and shutdown all AA services:

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

@@ -2,12 +2,12 @@
```eval_rst
.. 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):
::
::
supervisor stop myauth:
systemctl supervisor restart
supervisor stop myauth:
systemctl supervisor restart
```
## Task Logging
@@ -51,17 +51,17 @@ command=/home/allianceserver/venv/auth/bin/celery -A myauth worker --max-memory-
```eval_rst
.. 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 properly have more than one worker running in your system (if your workers run as processes, which is the default).
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 properly have more than one worker running in your system (if your workers run as processes, which is the default).
```
```eval_rst
.. warning::
The ``max-memory-per-child`` parameter only works when workers run as processes (which is the default). It does not work for threads.
The ``max-memory-per-child`` parameter only works when workers run as processes (which is the default). It does not work for threads.
```
```eval_rst
.. note::
Alternatively, you can also limit the number of runs per worker until a restart is performed with the worker parameter ``max-tasks-per-child``. This can also protect against memory leaks if you set the threshold is low enough. However, it is less precise since than using ``max-memory-per-child``.
Alternatively, you can also limit the number of runs per worker until a restart is performed with the worker parameter ``max-tasks-per-child``. This can also protect against memory leaks if you set the threshold is low enough. However, it is less precise since than using ``max-memory-per-child``.
```
See also the [official Celery documentation](https://docs.celeryproject.org/en/stable/userguide/workers.html#max-memory-per-child-setting) for more information about these two worker parameters.
@@ -109,11 +109,11 @@ The recommended number of workers is one per core, which is what you get automat
```eval_rst
.. 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 task load and verify your configuration is to run a model update with the following command:
::
celery -A myauth call allianceauth.eveonline.tasks.run_model_update
celery -A myauth call allianceauth.eveonline.tasks.run_model_update
```
@@ -125,7 +125,7 @@ Alliance Auth tasks are primarily I/O bound (most tasks are fetching data from E
```eval_rst
.. warning::
One important feature that no longer works with threads is the worker parameter ``--max-memory-per-child`` that protects against memory leaks. But you can alternatively use supervisor_ to monitor and restart your workers.
One important feature that no longer works with threads is the worker parameter ``--max-memory-per-child`` that protects against memory leaks. But you can alternatively use supervisor_ to monitor and restart your workers.
```
See also the also [this guide](https://www.distributedpython.com/2018/10/26/celery-execution-pool/) on more information about how to configure the execution pool for workers.
@@ -156,5 +156,5 @@ Make sure to restart supervisor to activate the changes.
```eval_rst
.. 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.
```

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

@@ -4,7 +4,7 @@ The official installation guide will install a stable version of Alliance Auth t
```eval_rst
.. 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 to their system.
```
```eval_rst