more automated upgrades

This commit is contained in:
Ariel Rin 2023-10-27 22:19:28 +10:00
parent ffb526ab0c
commit 906c589f14
No known key found for this signature in database
28 changed files with 96 additions and 133 deletions

View File

@ -2,10 +2,9 @@
It is possible to customize your **Alliance Auth** instance.
```{eval-rst}
.. warning::
:::{warning}
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
@ -111,10 +110,9 @@ nano /home/allianceserver/myauth/myauth/templates/allianceauth/side-menu.html
</li>
```
```{eval-rst}
.. hint::
:::{hint}
You can find other icons with a matching style on the `Font Awesome site <https://fontawesome.com/v5/search?m=free>`_ . AA currently uses Font Awesome version 5. You also want to keep the ``fa-fw`` tag to ensure all icons have the same width.
```
:::
### Step 4 - Restart your AA services

View File

@ -2,9 +2,9 @@
This section contains important information on how to develop Alliance Auth itself.
```{toctree}
:::{toctree}
:maxdepth: 1
documentation
code-style
```
:::

View File

@ -2,11 +2,11 @@
This section describes how to extend **Alliance Auth** with custom apps and services.
```{toctree}
:::{toctree}
:maxdepth: 1
integrating-services
menu-hooks
url-hooks
logging
```
:::

View File

@ -46,10 +46,9 @@ In order to integrate with Alliance Auth service modules must provide a `service
This would register the ExampleService class which would need to be a subclass of `services.hooks.ServiceHook`.
```{eval-rst}
.. important::
:::{important}
The hook **MUST** be registered in ``yourservice.auth_hooks`` along with any other hooks you are registering for Alliance Auth.
```
:::
A subclassed `ServiceHook` might look like this:

View File

@ -40,13 +40,11 @@ A list of views or namespaces the link should be highlighted on. See [django-nav
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.
```{eval-rst}
.. hint::
:::{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.
```
:::
To use it set count the `render()` function of your subclass in accordance to the current user. Here is an example:
```Python

View File

@ -6,10 +6,9 @@ The main benefit of this setup is that it runs all services and code in the nati
In addition all tools described in this guide are open source or free software.
```{eval-rst}
.. hint::
:::{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**.
```
:::
## Overview
@ -72,10 +71,8 @@ sudo apt-get install gettext
Next we need to install Python and related development tools.
```{eval-rst}
.. hint::
To check your system's Python 3 version you can enter: ``python3 --version``
```
:::{hint}
:::
:::{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
@ -179,10 +176,9 @@ Following this approach you can also setup additional AA projects, e.g. aa-dev-2
Create the root folder `aa-dev`.
```{eval-rst}
.. hint::
:::{hint}
The folders `venv` and `myauth` will be created automatically in later steps. Please do not create them manually as this would lead to errors.
```
:::
### Setup virtual Python environment for aa-dev
@ -240,10 +236,9 @@ For the Eve Online related setup you need to create a SSO app on the developer s
Open your local Django settings with VSC. The file is under `myauth/myauth/settings/local.py`
```{eval-rst}
.. hint::
:::{hint}
There are two Django settings files: ``base.py`` and ``local.py``. The base settings file is controlled by the AA project and may change at any time. It is therefore recommended to only change the local settings file.
```
:::
```python
DEBUG = True
@ -312,10 +307,9 @@ 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`
```{eval-rst}
.. hint::
:::{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).
```
:::
:::{note}
**Debug vs. Non-Debug mode**

View File

@ -2,8 +2,8 @@
Here you find guides on how to setup your development environment for AA.
```{toctree}
:::{toctree}
:maxdepth: 1
aa-dev-setup-wsl-vsc-v2
```
:::

View File

@ -2,11 +2,11 @@
**Alliance Auth** is designed to be extended easily. Learn how to develop your own apps and services for AA or to develop for AA core in the development chapter.
```{toctree}
:::{toctree}
:maxdepth: 1
custom/index
aa_core/index
dev_setup/index
tech_docu/index
```
:::

View File

@ -2,7 +2,7 @@
To reduce redundancy and help speed up development we encourage developers to utilize the following packages when developing apps for Alliance Auth.
```{toctree}
:::{toctree}
:maxdepth: 1
discord_client
@ -13,4 +13,4 @@ eveonline
notifications
testutils
utils
```
:::

View File

@ -105,14 +105,13 @@ In this example we fist add 10 example tasks that need to run one after the othe
The list of task signatures is then converted to a chain and started asynchronously.
```{eval-rst}
.. hint::
:::{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.
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.
```
:::
## How can I define periodic tasks for my app?
@ -149,18 +148,14 @@ In Alliance Auth we have defined task priorities from 0 - 9 as follows:
====== ========= ===========
```
```{eval-rst}
.. warning::
:::{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)
```
```{eval-rst}
.. hint::
:::
:::{hint}
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.
Example for starting a task with priority 3:
@ -169,10 +164,9 @@ Example for starting a task with priority 3:
example.apply_async(priority=3)
```
```{eval-rst}
.. hint::
:::{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.
```
:::
## What special features should I be aware of?

View File

@ -2,11 +2,11 @@
In this section you find topics useful for app developers.
```{toctree}
:::{toctree}
:maxdepth: 1
api/index
celery
core_models
templatetags
```
:::

View File

@ -18,11 +18,9 @@ When you create an autogroup config you will be given the following options:
![Create Autogroup page](/_static/images/features/apps/autogroups/group-creation.png)
```{eval-rst}
.. warning::
:::{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.
```
:::
- States selects which states will be added to automatic Corp/Alliance groups
- Corp/Alliance groups checkbox toggles Corp/Alliance autogroups on or off for this config.

View File

@ -2,7 +2,7 @@
**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.
```{toctree}
:::{toctree}
:maxdepth: 1
autogroups
@ -13,4 +13,4 @@ optimer
permissions_tool
srp
timerboard
```
:::

View File

@ -10,11 +10,9 @@ You can open the admin site by clicking on "Admin" in the drop down menu for a u
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.
```{eval-rst}
.. warning::
:::{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.
```
:::
## 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.
@ -41,10 +39,9 @@ To create a staff admin you need to do two things:
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
process will automatically have access to the admin site.
```{eval-rst}
.. hint::
:::{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.
```
:::
### Permissions for common admin tasks

View File

@ -2,7 +2,7 @@
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.
```{toctree}
:::{toctree}
:maxdepth: 1
dashboard
@ -11,4 +11,4 @@ groups
analytics
notifications
admin_site
```
:::

View File

@ -2,7 +2,7 @@
Learn about the features of **Alliance Auth** and how to install and use them.
```{toctree}
:::{toctree}
:maxdepth: 1
overview
@ -10,4 +10,4 @@ core/index
services/index
apps/index
community/index
```
:::

View File

@ -4,7 +4,7 @@
## Supported Services
```{toctree}
:::{toctree}
:maxdepth: 1
discord
@ -15,13 +15,13 @@ phpbb3
smf
teamspeak3
xenforo
```
:::
## Tools
```{toctree}
:::{toctree}
:maxdepth: 1
nameformats
permissions
```
:::

View File

@ -6,11 +6,9 @@ Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all
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}
.. warning::
:::{warning}
This guide is currently for Ubuntu only.
```
:::
## Installations
### Installing Mumble Server

View File

@ -70,12 +70,10 @@ Some examples of strings you could use:
+------------------------------------------+---------------------------+
```
```{eval-rst}
.. important::
:::{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.
```
:::
```{eval-rst}
.. important::
:::{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.
```
:::

View File

@ -6,10 +6,9 @@ In the past, access to services was dictated by a list of settings in `settings.
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.
```{eval-rst}
.. important::
:::{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.
```
:::
Each service has an access permission defined, named like `Can access the <service name> service`.
@ -19,10 +18,9 @@ A user can be granted the same permission from multiple sources. e.g. they may h
## Removing access
```{eval-rst}
.. danger::
:::{danger}
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.

View File

@ -48,18 +48,18 @@ unzip smf_2-1-2_install.zip
Now we need to move this to our web directory. Usually `/var/www/forums`.
```shell
mv smf /var/www/forums
````
```
The web server needs read/write permission to this folder
Apache: `chown -R www-data:www-data /var/www/forums`
Nginx: `chown -R nginx:nginx /var/www/forums`
```{eval-rst}
.. tip::
:::{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.
..
```
:::
### Database Preparation

View File

@ -7,7 +7,7 @@ Welcome to the official documentation for **Alliance Auth**!
**Alliance Auth** is a web site that helps Eve Online organizations efficiently manage access to applications and external services.
```{toctree}
:::{toctree}
:maxdepth: 2
:caption: Contents
@ -18,4 +18,4 @@ support/index
customizing/index
development/index
contributing/index
```
:::

View File

@ -4,7 +4,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).
```{toctree}
:::{toctree}
:maxdepth: 1
allianceauth
@ -13,4 +13,4 @@ apache
gunicorn
upgrade_python
switch_to_non_root
```
:::

View File

@ -33,12 +33,11 @@ Install Nginx via your preferred package manager or other method. If you need he
Nginx needs to be able to read the folder containing your auth project's static files. `chown -R nginx:nginx /var/www/myauth/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.
..
```
:::{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.
:::
You will need to have [Gunicorn](gunicorn.md) or some other WSGI server setup for hosting Alliance Auth.

View File

@ -165,14 +165,12 @@ At this point we recommend creating a list of the additional packages that you n
- Community AA apps (e.g. aa-structures)
- Additional tools you are using (e.g. flower, django-extensions)
```{eval-rst}
.. hint::
:::{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.
```
:::
:::{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.
```
:::
Leave the venv and shutdown all AA services:

View File

@ -2,11 +2,11 @@
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}
:::{toctree}
:maxdepth: 1
apps
project
troubleshooting
tuning/index
```
:::

View File

@ -1,14 +1,13 @@
# Celery
```{eval-rst}
.. hint::
:::{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):
::
supervisor stop myauth:
systemctl supervisor restart
```
:::
## Task Logging
@ -28,10 +27,9 @@ command=/home/allianceserver/venv/auth/bin/celery -A myauth worker -l info
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.
```{eval-rst}
.. hint::
:::{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.
```
:::
### Supervisor
@ -90,15 +88,14 @@ command=... -p worker_00=256MB -p worker_01=256MB -p worker_02=256MB
...
```
```{eval-rst}
.. hint::
:::{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:
::
celery -A myauth call allianceauth.eveonline.tasks.run_model_update
```
:::
### Concurrency
@ -108,17 +105,15 @@ This can be achieved by the setting the concurrency parameter of the celery work
--concurrency=10
```
```{eval-rst}
.. hint::
:::{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:
::
celery -A myauth call allianceauth.eveonline.tasks.run_model_update
```
:::
```{eval-rst}
.. hint::
:::{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.
```
:::

View File

@ -2,15 +2,14 @@
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.
```{eval-rst}
.. warning::
:::{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.
```
:::
```{toctree}
:::{toctree}
:maxdepth: 1
gunicorn
celery
redis
```
:::